@ioka-technologies/asyncapi-rust-client-template 0.0.30 → 0.0.32

package/dist/common/index.js

@@ -2305,6 +2305,14 @@ function generateRustModels(asyncapi, options = {}) {
             return 'u32';
           case 'uint64':
             return 'u64';
+          case 'uint16':
+            return 'u16';
+          case 'uint8':
+            return 'u8';
+          case 'int16':
+            return 'i16';
+          case 'int8':
+            return 'i8';
           default:
             // Default to i32 for unspecified format (maintains backward compatibility)
             return 'i32';
@@ -2718,6 +2726,287 @@ function generateMessageEnvelope() {
   return `use serde::{de::DeserializeOwned, Deserialize, Serialize};
 use std::collections::HashMap;
 use uuid::Uuid;
+use chrono::{DateTime, Utc};
+
+/// Correlation ID for tracing errors across operations
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct CorrelationId(pub Uuid);
+
+impl CorrelationId {
+    pub fn new() -> Self {
+        Self(Uuid::new_v4())
+    }
+}
+
+impl std::fmt::Display for CorrelationId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl Default for CorrelationId {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Error severity levels for categorization and alerting
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ErrorSeverity {
+    /// Low severity - informational, no action required
+    Low,
+    /// Medium severity - warning, monitoring required
+    Medium,
+    /// High severity - error, immediate attention needed
+    High,
+    /// Critical severity - system failure, urgent action required
+    Critical,
+}
+
+impl std::fmt::Display for ErrorSeverity {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ErrorSeverity::Low => write!(f, "LOW"),
+            ErrorSeverity::Medium => write!(f, "MEDIUM"),
+            ErrorSeverity::High => write!(f, "HIGH"),
+            ErrorSeverity::Critical => write!(f, "CRITICAL"),
+        }
+    }
+}
+
+/// Error category for classification and handling
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ErrorCategory {
+    /// Configuration-related errors
+    Configuration,
+    /// Network and protocol errors
+    Network,
+    /// Message validation errors
+    Validation,
+    /// Business logic errors
+    BusinessLogic,
+    /// System resource errors
+    Resource,
+    /// Security-related errors
+    Security,
+    /// Serialization/deserialization errors
+    Serialization,
+    /// Routing errors
+    Routing,
+    /// Authorization errors
+    Authorization,
+    /// Unknown or unclassified errors
+    Unknown,
+}
+
+impl std::fmt::Display for ErrorCategory {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ErrorCategory::Configuration => write!(f, "CONFIGURATION"),
+            ErrorCategory::Network => write!(f, "NETWORK"),
+            ErrorCategory::Validation => write!(f, "VALIDATION"),
+            ErrorCategory::BusinessLogic => write!(f, "BUSINESS_LOGIC"),
+            ErrorCategory::Resource => write!(f, "RESOURCE"),
+            ErrorCategory::Security => write!(f, "SECURITY"),
+            ErrorCategory::Serialization => write!(f, "SERIALIZATION"),
+            ErrorCategory::Routing => write!(f, "ROUTING"),
+            ErrorCategory::Authorization => write!(f, "AUTHORIZATION"),
+            ErrorCategory::Unknown => write!(f, "UNKNOWN"),
+        }
+    }
+}
+
+/// Error metadata for enhanced context and monitoring
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ErrorMetadata {
+    pub correlation_id: CorrelationId,
+    pub severity: ErrorSeverity,
+    pub category: ErrorCategory,
+    pub timestamp: DateTime<Utc>,
+    pub retryable: bool,
+    pub kind: u32,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source_location: Option<String>,
+    #[serde(skip_serializing_if = "HashMap::is_empty", default)]
+    pub additional_context: HashMap<String, String>,
+}
+
+impl ErrorMetadata {
+    pub fn new(severity: ErrorSeverity, category: ErrorCategory, retryable: bool) -> Self {
+        Self {
+            correlation_id: CorrelationId::new(),
+            severity,
+            category,
+            timestamp: Utc::now(),
+            retryable,
+            kind: 0,
+            source_location: None,
+            additional_context: HashMap::new(),
+        }
+    }
+
+    pub fn with_kind(mut self, kind: u32) -> Self {
+        self.kind = kind;
+        self
+    }
+}
+
+/// Serializable AsyncAPI error for wire transmission
+///
+/// This error type can be sent between server and client while preserving
+/// all the rich error information needed for proper error handling.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "error_type", content = "details")]
+pub enum AsyncApiError {
+    #[serde(rename = "configuration")]
+    Configuration {
+        message: String,
+        metadata: ErrorMetadata,
+    },
+
+    #[serde(rename = "protocol")]
+    Protocol {
+        message: String,
+        protocol: String,
+        metadata: ErrorMetadata,
+    },
+
+    #[serde(rename = "validation")]
+    Validation {
+        message: String,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        field: Option<String>,
+        metadata: ErrorMetadata,
+    },
+
+    #[serde(rename = "handler")]
+    Handler {
+        message: String,
+        handler_name: String,
+        metadata: ErrorMetadata,
+    },
+
+    #[serde(rename = "middleware")]
+    Middleware {
+        message: String,
+        middleware_name: String,
+        metadata: ErrorMetadata,
+    },
+
+    #[serde(rename = "recovery")]
+    Recovery {
+        message: String,
+        attempts: u32,
+        metadata: ErrorMetadata,
+    },
+
+    #[serde(rename = "resource")]
+    Resource {
+        message: String,
+        resource_type: String,
+        metadata: ErrorMetadata,
+    },
+
+    #[serde(rename = "security")]
+    Security {
+        message: String,
+        metadata: ErrorMetadata,
+    },
+
+    #[serde(rename = "authentication")]
+    Authentication {
+        message: String,
+        auth_method: String,
+        metadata: ErrorMetadata,
+    },
+
+    #[serde(rename = "authorization")]
+    Authorization {
+        message: String,
+        required_permissions: Vec<String>,
+        metadata: ErrorMetadata,
+    },
+
+    #[serde(rename = "rate_limit")]
+    RateLimit {
+        message: String,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        retry_after_secs: Option<u64>,
+    },
+
+    #[serde(rename = "context")]
+    Context {
+        message: String,
+        context_key: String,
+        metadata: ErrorMetadata,
+    },
+}
+
+impl AsyncApiError {
+    /// Get error message
+    pub fn message(&self) -> &str {
+        match self {
+            AsyncApiError::Configuration { message, .. } => message,
+            AsyncApiError::Protocol { message, .. } => message,
+            AsyncApiError::Validation { message, .. } => message,
+            AsyncApiError::Handler { message, .. } => message,
+            AsyncApiError::Middleware { message, .. } => message,
+            AsyncApiError::Recovery { message, .. } => message,
+            AsyncApiError::Resource { message, .. } => message,
+            AsyncApiError::Security { message, .. } => message,
+            AsyncApiError::Authentication { message, .. } => message,
+            AsyncApiError::Authorization { message, .. } => message,
+            AsyncApiError::RateLimit { message, .. } => message,
+            AsyncApiError::Context { message, .. } => message,
+        }
+    }
+
+    /// Get error metadata (if available)
+    pub fn metadata(&self) -> Option<&ErrorMetadata> {
+        match self {
+            AsyncApiError::Configuration { metadata, .. } => Some(metadata),
+            AsyncApiError::Protocol { metadata, .. } => Some(metadata),
+            AsyncApiError::Validation { metadata, .. } => Some(metadata),
+            AsyncApiError::Handler { metadata, .. } => Some(metadata),
+            AsyncApiError::Middleware { metadata, .. } => Some(metadata),
+            AsyncApiError::Recovery { metadata, .. } => Some(metadata),
+            AsyncApiError::Resource { metadata, .. } => Some(metadata),
+            AsyncApiError::Security { metadata, .. } => Some(metadata),
+            AsyncApiError::Authentication { metadata, .. } => Some(metadata),
+            AsyncApiError::Authorization { metadata, .. } => Some(metadata),
+            AsyncApiError::Context { metadata, .. } => Some(metadata),
+            AsyncApiError::RateLimit { .. } => None,
+        }
+    }
+
+    /// Check if error is retryable
+    pub fn is_retryable(&self) -> bool {
+        self.metadata().map_or(false, |m| m.retryable)
+    }
+
+    /// Get error severity
+    pub fn severity(&self) -> Option<ErrorSeverity> {
+        self.metadata().map(|m| m.severity)
+    }
+
+    /// Get error category
+    pub fn category(&self) -> Option<ErrorCategory> {
+        self.metadata().map(|m| m.category)
+    }
+
+    /// Get correlation ID for tracing
+    pub fn correlation_id(&self) -> Option<&CorrelationId> {
+        self.metadata().map(|m| &m.correlation_id)
+    }
+}
+
+impl std::fmt::Display for AsyncApiError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.message())
+    }
+}
+
+impl std::error::Error for AsyncApiError {}
 
 /// Unified message envelope for consistent AsyncAPI message format
 ///
@@ -2791,17 +3080,9 @@ pub struct MessageEnvelope {
     pub channel: Option<String>,
     /// Transport-level headers (auth, routing, etc.)
     pub headers: Option<HashMap<String, String>>,
-    /// Error information if applicable
-    pub error: Option<MessageError>,
-}
-
-/// Error information for failed operations
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-pub struct MessageError {
-    /// Error code (e.g., "VALIDATION_ERROR", "TIMEOUT", "UNAUTHORIZED")
-    pub code: String,
-    /// Human-readable error message
-    pub message: String,
+    /// Rich error information if operation failed
+    /// Contains detailed error metadata including severity, category, and correlation
+    pub error: Option<AsyncApiError>,
 }
 
 impl MessageEnvelope {
@@ -2839,11 +3120,10 @@ impl MessageEnvelope {
         Ok(envelope)
     }
 
-    /// Create an error response envelope
+    /// Create an error response envelope with rich AsyncApiError
     pub fn error_response(
         operation: &str,
-        error_code: &str,
-        error_message: &str,
+        error: AsyncApiError,
         correlation_id: Option<String>,
     ) -> Self {
         Self {
@@ -2854,13 +3134,28 @@ impl MessageEnvelope {
             correlation_id,
             channel: None,
             headers: None,
-            error: Some(MessageError {
-                code: error_code.to_string(),
-                message: error_message.to_string(),
-            }),
+            error: Some(error),
         }
     }
 
+    /// Create a simple error response envelope (for backward compatibility)
+    pub fn simple_error_response(
+        operation: &str,
+        error_message: &str,
+        correlation_id: Option<String>,
+    ) -> Self {
+        let error = AsyncApiError::Handler {
+            message: error_message.to_string(),
+            handler_name: operation.to_string(),
+            metadata: ErrorMetadata::new(
+                ErrorSeverity::High,
+                ErrorCategory::BusinessLogic,
+                false,
+            ),
+        };
+        Self::error_response(operation, error, correlation_id)
+    }
+
     /// Set the correlation ID for this envelope
     pub fn with_correlation_id(mut self, id: String) -> Self {
         self.correlation_id = Some(id);
@@ -2904,11 +3199,23 @@ impl MessageEnvelope {
     }
 
     /// Set an error on this envelope
-    pub fn with_error(mut self, code: &str, message: &str) -> Self {
-        self.error = Some(MessageError {
-            code: code.to_string(),
+    pub fn with_error(mut self, error: AsyncApiError) -> Self {
+        self.error = Some(error);
+        self
+    }
+
+    /// Set a simple error on this envelope (for backward compatibility)
+    pub fn with_simple_error(mut self, message: &str) -> Self {
+        let error = AsyncApiError::Handler {
             message: message.to_string(),
-        });
+            handler_name: self.operation.clone(),
+            metadata: ErrorMetadata::new(
+                ErrorSeverity::High,
+                ErrorCategory::BusinessLogic,
+                false,
+            ),
+        };
+        self.error = Some(error);
         self
     }
 
@@ -2950,134 +3257,6 @@ impl MessageEnvelope {
     }
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use serde::{Deserialize, Serialize};
-
-    #[derive(Debug, Serialize, Deserialize, PartialEq)]
-    struct TestPayload {
-        message: String,
-        count: u32,
-    }
-
-    #[test]
-    fn test_envelope_creation() {
-        let payload = TestPayload {
-            message: "test".to_string(),
-            count: 42,
-        };
-
-        let envelope = MessageEnvelope::new("test_operation", &payload).unwrap();
-
-        assert_eq!(envelope.operation, "test_operation");
-        assert!(!envelope.id.is_empty());
-        assert!(!envelope.timestamp.is_empty());
-        assert_eq!(envelope.correlation_id, None);
-        assert_eq!(envelope.error, None);
-
-        let extracted: TestPayload = envelope.extract_payload().unwrap();
-        assert_eq!(extracted, payload);
-    }
-
-    #[test]
-    fn test_envelope_with_correlation_id() {
-        let payload = TestPayload {
-            message: "test".to_string(),
-            count: 42,
-        };
-
-        let correlation_id = "test-correlation-id".to_string();
-        let envelope = MessageEnvelope::new_with_correlation_id(
-            "test_operation",
-            &payload,
-            correlation_id.clone(),
-        ).unwrap();
-
-        assert_eq!(envelope.correlation_id, Some(correlation_id));
-    }
-
-    #[test]
-    fn test_error_response() {
-        let error_envelope = MessageEnvelope::error_response(
-            "test_operation_response",
-            "TEST_ERROR",
-            "Test error message",
-            Some("correlation-123".to_string()),
-        );
-
-        assert!(error_envelope.is_error());
-        assert_eq!(error_envelope.correlation_id, Some("correlation-123".to_string()));
-        if let Some(error) = &error_envelope.error {
-            assert_eq!(error.code, "TEST_ERROR");
-            assert_eq!(error.message, "Test error message");
-        }
-    }
-
-    #[test]
-    fn test_envelope_serialization() {
-        let payload = TestPayload {
-            message: "test".to_string(),
-            count: 42,
-        };
-
-        let envelope = MessageEnvelope::new("test_operation", &payload).unwrap();
-        let bytes = envelope.to_bytes().unwrap();
-        let deserialized = MessageEnvelope::from_bytes(&bytes).unwrap();
-
-        assert_eq!(envelope.id, deserialized.id);
-        assert_eq!(envelope.operation, deserialized.operation);
-        assert_eq!(envelope.timestamp, deserialized.timestamp);
-    }
-
-    #[test]
-    fn test_response_creation() {
-        let request_payload = TestPayload {
-            message: "request".to_string(),
-            count: 1,
-        };
-
-        let response_payload = TestPayload {
-            message: "response".to_string(),
-            count: 2,
-        };
-
-        let request = MessageEnvelope::new_with_correlation_id(
-            "test_request",
-            &request_payload,
-            "test-correlation".to_string(),
-        ).unwrap();
-
-        let response = request.create_response("test_response", &response_payload).unwrap();
-
-        assert_eq!(response.operation, "test_response");
-        assert_eq!(response.correlation_id, request.correlation_id);
-
-        let extracted: TestPayload = response.extract_payload().unwrap();
-        assert_eq!(extracted, response_payload);
-    }
-
-    #[test]
-    fn test_headers_and_auth() {
-        let payload = TestPayload {
-            message: "test".to_string(),
-            count: 42,
-        };
-
-        let mut auth_headers = HashMap::new();
-        auth_headers.insert("Authorization".to_string(), "Bearer token123".to_string());
-
-        let envelope = MessageEnvelope::new("test_operation", &payload)
-            .unwrap()
-            .with_auth_headers(auth_headers)
-            .with_header("Custom-Header".to_string(), "custom-value".to_string());
-
-        assert!(envelope.headers.is_some());
-        let headers = envelope.headers.unwrap();
-        assert_eq!(headers.get("Authorization"), Some(&"Bearer token123".to_string()));
-        assert_eq!(headers.get("Custom-Header"), Some(&"custom-value".to_string()));
-    }
-}
 `;
 }
 ;// ../common/src/models-ts.js

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ioka-technologies/asyncapi-rust-client-template",
-    "version": "0.0.30",
+    "version": "0.0.32",
     "description": "AsyncAPI template for generating Rust NATS clients",
     "main": "template/index.js",
     "keywords": [

package/template/src/client.rs.js

@@ -190,6 +190,7 @@ export default function ClientRs({ asyncapi, params }) {
     /// * \`ClientError::Nats\` - NATS operation failed
     /// * \`ClientError::Serialization\` - Failed to serialize/deserialize data
     /// * \`ClientError::Timeout\` - Request timed out
+    /// * \`ClientError::AsyncApi\` - Server returned an error
     pub async fn ${op.methodName}(&self, payload: ${op.requestType}) -> ClientResult<${op.responseType}> {
         let envelope = if let Some(ref auth) = self.auth {
             MessageEnvelope::new_with_auth("${op.operationName}", payload, auth)
@@ -208,6 +209,11 @@ export default function ClientRs({ asyncapi, params }) {
         let response_envelope = MessageEnvelope::from_bytes(&response.payload)
             .map_err(|e| ClientError::InvalidEnvelope(e.to_string()))?;
 
+        // Check if the response contains an error
+        if let Some(error) = response_envelope.error {
+            return Err(ClientError::AsyncApi(Box::new(error)));
+        }
+
         let result: ${op.responseType} = response_envelope.extract_payload()
             .map_err(ClientError::Serialization)?;
 
@@ -399,6 +405,7 @@ ${serviceOperations}
     /// * \`ClientError::Nats\` - NATS operation failed
     /// * \`ClientError::Serialization\` - Failed to serialize/deserialize data
     /// * \`ClientError::Timeout\` - Request timed out
+    /// * \`ClientError::AsyncApi\` - Server returned an error
     pub async fn ${pattern.methodName}(&self, payload: ${pattern.requestType}) -> ClientResult<${pattern.responseType}> {
         let envelope = if let Some(ref auth) = self.auth {
             MessageEnvelope::new_with_auth("${pattern.operationName}", payload, auth)
@@ -416,6 +423,11 @@ ${serviceOperations}
         let response_envelope = MessageEnvelope::from_bytes(&response.payload)
             .map_err(|e| ClientError::InvalidEnvelope(e.to_string()))?;
 
+        // Check if the response contains an error
+        if let Some(error) = response_envelope.error {
+            return Err(ClientError::AsyncApi(Box::new(error)));
+        }
+
         let result: ${pattern.responseType} = response_envelope.extract_payload()
             .map_err(ClientError::Serialization)?;
 

package/template/src/envelope.rs.js

@@ -1,196 +1,28 @@
 /* eslint-disable no-unused-vars */
 import { File } from '@asyncapi/generator-react-sdk';
+import { generateMessageEnvelope } from "../../dist/common/index.js";
 
 export default function ({ asyncapi, params }) {
+    // Generate the unified message envelope with error support
+    const envelopeCode = generateMessageEnvelope();
+
     return (
         <File name="envelope.rs">
             {`//! Message envelope for consistent NATS message format
 
 use crate::auth::{AuthCredentials, generate_auth_headers};
-use serde::{Deserialize, Serialize};
-use std::collections::HashMap;
-use uuid::Uuid;
-
-/// MessageEnvelope for consistent message format across NATS operations
-/// This matches the format expected by the server implementation
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct MessageEnvelope {
-    /// Unique message identifier
-    pub id: String,
-    /// Operation name from AsyncAPI spec
-    pub operation: String,
-    /// Message payload as JSON value
-    pub payload: serde_json::Value,
-    /// ISO 8601 timestamp when message was created
-    pub timestamp: String,
-    /// Optional correlation ID for request/reply patterns
-    pub correlation_id: Option<String>,
-    /// Optional headers for additional metadata
-    pub headers: Option<HashMap<String, String>>,
-}
+${envelopeCode}
 
+// Client-specific extensions for auth integration
 impl MessageEnvelope {
-    /// Create a new message envelope with generated ID and current timestamp
-    pub fn new<T: Serialize>(operation: &str, payload: T) -> Result<Self, serde_json::Error> {
-        Ok(Self {
-            id: Uuid::new_v4().to_string(),
-            operation: operation.to_string(),
-            payload: serde_json::to_value(payload)?,
-            timestamp: chrono::Utc::now().to_rfc3339(),
-            correlation_id: None,
-            headers: None,
-        })
-    }
-
-    /// Create a new message envelope with a specific correlation ID
-    pub fn new_with_correlation_id<T: Serialize>(
-        operation: &str,
-        payload: T,
-        correlation_id: String,
-    ) -> Result<Self, serde_json::Error> {
-        Ok(Self {
-            id: Uuid::new_v4().to_string(),
-            operation: operation.to_string(),
-            payload: serde_json::to_value(payload)?,
-            timestamp: chrono::Utc::now().to_rfc3339(),
-            correlation_id: Some(correlation_id),
-            headers: None,
-        })
-    }
-
-    /// Add headers to the envelope
-    pub fn with_headers(mut self, headers: HashMap<String, String>) -> Self {
-        self.headers = Some(headers);
-        self
-    }
-
-    /// Add a single header to the envelope
-    pub fn with_header(mut self, key: String, value: String) -> Self {
-        if let Some(ref mut headers) = self.headers {
-            headers.insert(key, value);
-        } else {
-            let mut headers = HashMap::new();
-            headers.insert(key, value);
-            self.headers = Some(headers);
-        }
-        self
-    }
-
-    /// Add authentication headers to the envelope
-    pub fn with_auth_headers(mut self, auth: &AuthCredentials) -> Self {
-        let auth_headers = generate_auth_headers(auth);
-        if !auth_headers.is_empty() {
-            if let Some(ref mut headers) = self.headers {
-                headers.extend(auth_headers);
-            } else {
-                self.headers = Some(auth_headers);
-            }
-        }
-        self
-    }
-
     /// Create a new message envelope with authentication headers
     pub fn new_with_auth<T: Serialize>(
         operation: &str,
         payload: T,
         auth: &AuthCredentials,
     ) -> Result<Self, serde_json::Error> {
-        let envelope = Self::new(operation, payload)?;
-        Ok(envelope.with_auth_headers(auth))
-    }
-
-    /// Create a new message envelope with correlation ID and authentication headers
-    pub fn new_with_correlation_id_and_auth<T: Serialize>(
-        operation: &str,
-        payload: T,
-        correlation_id: String,
-        auth: &AuthCredentials,
-    ) -> Result<Self, serde_json::Error> {
-        let envelope = Self::new_with_correlation_id(operation, payload, correlation_id)?;
-        Ok(envelope.with_auth_headers(auth))
-    }
-
-    /// Convert the envelope to bytes for NATS transmission
-    pub fn to_bytes(&self) -> Result<Vec<u8>, serde_json::Error> {
-        serde_json::to_vec(self)
-    }
-
-    /// Parse envelope from bytes received from NATS
-    pub fn from_bytes(bytes: &[u8]) -> Result<Self, serde_json::Error> {
-        serde_json::from_slice(bytes)
-    }
-
-    /// Extract the payload as a specific type
-    pub fn extract_payload<T: for<'de> Deserialize<'de>>(&self) -> Result<T, serde_json::Error> {
-        serde_json::from_value(self.payload.clone())
-    }
-
-    /// Get the correlation ID if present
-    pub fn correlation_id(&self) -> Option<&str> {
-        self.correlation_id.as_deref()
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use serde::{Deserialize, Serialize};
-
-    #[derive(Debug, Serialize, Deserialize, PartialEq)]
-    struct TestPayload {
-        message: String,
-        count: u32,
-    }
-
-    #[test]
-    fn test_envelope_creation() {
-        let payload = TestPayload {
-            message: "test".to_string(),
-            count: 42,
-        };
-
-        let envelope = MessageEnvelope::new("test_operation", &payload).unwrap();
-
-        assert_eq!(envelope.operation, "test_operation");
-        assert!(!envelope.id.is_empty());
-        assert!(!envelope.timestamp.is_empty());
-        assert_eq!(envelope.correlation_id, None);
-
-        let extracted: TestPayload = envelope.extract_payload().unwrap();
-        assert_eq!(extracted, payload);
-    }
-
-    #[test]
-    fn test_envelope_with_correlation_id() {
-        let payload = TestPayload {
-            message: "test".to_string(),
-            count: 42,
-        };
-
-        let correlation_id = "test-correlation-id".to_string();
-        let envelope = MessageEnvelope::new_with_correlation_id(
-            "test_operation",
-            &payload,
-            correlation_id.clone(),
-        ).unwrap();
-
-        assert_eq!(envelope.correlation_id(), Some(correlation_id.as_str()));
-    }
-
-    #[test]
-    fn test_envelope_serialization() {
-        let payload = TestPayload {
-            message: "test".to_string(),
-            count: 42,
-        };
-
-        let envelope = MessageEnvelope::new("test_operation", &payload).unwrap();
-        let bytes = envelope.to_bytes().unwrap();
-        let deserialized = MessageEnvelope::from_bytes(&bytes).unwrap();
-
-        assert_eq!(envelope.id, deserialized.id);
-        assert_eq!(envelope.operation, deserialized.operation);
-        assert_eq!(envelope.timestamp, deserialized.timestamp);
+        let auth_headers = generate_auth_headers(auth);
+        Self::new(operation, payload).map(|envelope| envelope.with_auth_headers(auth_headers))
     }
 }
 `}

package/template/src/envelope.rs.js.dev

@@ -0,0 +1,31 @@
+/* eslint-disable no-unused-vars */
+import { File } from '@asyncapi/generator-react-sdk';
+import { generateMessageEnvelope } from '../../../common/src/index.js';
+
+export default function ({ asyncapi, params }) {
+    // Generate the unified message envelope with error support
+    const envelopeCode = generateMessageEnvelope();
+
+    return (
+        <File name="envelope.rs">
+            {`//! Message envelope for consistent NATS message format
+
+use crate::auth::{AuthCredentials, generate_auth_headers};
+${envelopeCode}
+
+// Client-specific extensions for auth integration
+impl MessageEnvelope {
+    /// Create a new message envelope with authentication headers
+    pub fn new_with_auth<T: Serialize>(
+        operation: &str,
+        payload: T,
+        auth: &AuthCredentials,
+    ) -> Result<Self, serde_json::Error> {
+        let auth_headers = generate_auth_headers(auth);
+        Self::new(operation, payload).map(|envelope| envelope.with_auth_headers(auth_headers))
+    }
+}
+`}
+        </File>
+    );
+};

package/template/src/errors.rs.js

@@ -9,6 +9,9 @@ export default function ({ asyncapi, params }) {
 use crate::auth::AuthError;
 use thiserror::Error;
 
+// Import the shared AsyncApiError type from the envelope/models module
+pub use crate::envelope::{AsyncApiError, ErrorSeverity, ErrorCategory, ErrorMetadata, CorrelationId as ErrorCorrelationId};
+
 /// Errors that can occur when using the NATS client
 #[derive(Debug, Error)]
 pub enum ClientError {
@@ -39,6 +42,58 @@ pub enum ClientError {
     /// Unauthorized access
     #[error("Unauthorized: {0}")]
     Unauthorized(String),
+
+    /// Server-side AsyncAPI error
+    ///
+    /// This error contains rich information from the server including:
+    /// - Error severity and category
+    /// - Correlation ID for tracing
+    /// - Detailed error metadata
+    /// - Whether the error is retryable
+    #[error("Server error: {0}")]
+    AsyncApi(Box<AsyncApiError>),
+}
+
+impl ClientError {
+    /// Check if this error is retryable
+    pub fn is_retryable(&self) -> bool {
+        match self {
+            ClientError::Nats(_) => true,
+            ClientError::Timeout => true,
+            ClientError::NoResponse => true,
+            ClientError::AsyncApi(err) => err.is_retryable(),
+            _ => false,
+        }
+    }
+
+    /// Get error severity if available
+    pub fn severity(&self) -> Option<ErrorSeverity> {
+        match self {
+            ClientError::AsyncApi(err) => err.severity(),
+            _ => None,
+        }
+    }
+
+    /// Get error category if available
+    pub fn category(&self) -> Option<ErrorCategory> {
+        match self {
+            ClientError::AsyncApi(err) => err.category(),
+            _ => None,
+        }
+    }
+
+    /// Get correlation ID for tracing if available
+    pub fn correlation_id(&self) -> Option<&ErrorCorrelationId> {
+        match self {
+            ClientError::AsyncApi(err) => err.correlation_id(),
+            _ => None,
+        }
+    }
+
+    /// Check if this is a server-side error
+    pub fn is_server_error(&self) -> bool {
+        matches!(self, ClientError::AsyncApi(_))
+    }
 }
 
 /// Result type alias for client operations