Add response.done message handling for Realtime API error reporting

- Add responseDone case to OpenAIRealtimeMessage enum to capture response completion events
- Implement handler for response.done messages in OpenAIRealtimeSession
- Parse and expose error details from status_details.error for API errors (insufficient_quota, invalid_api_key, etc.)
- Improve logging: upgrade unhandled message warnings from debug to warning level
- Add detailed JSON logging for debugging unhandled message types

This change ensures that critical API errors like quota exhaustion and authentication failures are properly surfaced to consuming applications instead of being silently discarded.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: jamesrochabrun

Sources/OpenAI/Private/Realtime/OpenAIRealtimeSession.swift

@@ -249,9 +249,31 @@ open class OpenAIRealtimeSession {
 
       continuation?.yield(.mcpListToolsFailed(fullError))
 
+    case "response.done":
+      // Handle response completion (may contain errors like insufficient_quota)
+      if let response = json["response"] as? [String: Any],
+         let status = response["status"] as? String {
+
+        logger.debug("Response done with status: \(status)")
+
+        // Pass the full response object for detailed error handling
+        continuation?.yield(.responseDone(status: status, statusDetails: response))
+
+        // Log errors for debugging
+        if let statusDetails = response["status_details"] as? [String: Any],
+           let error = statusDetails["error"] as? [String: Any] {
+          let code = error["code"] as? String ?? "unknown"
+          let message = error["message"] as? String ?? "Unknown error"
+          logger.error("Response error: [\(code)] \(message)")
+        }
+      } else {
+        logger.warning("Received response.done with unexpected format")
+      }
+
     default:
-      // Log unhandled message types for debugging
-      logger.debug("Unhandled message type: \(messageType)")
+      // Log unhandled message types with more detail for debugging
+      logger.warning("⚠️ Unhandled message type: \(messageType)")
+      logger.debug("Full JSON: \(String(describing: json))")
       break
     }
 

Sources/OpenAI/Public/ResponseModels/Realtime/OpenAIRealtimeMessage.swift

@@ -26,4 +26,7 @@ public enum OpenAIRealtimeMessage: Sendable {
   case mcpListToolsInProgress // "mcp_list_tools.in_progress"
   case mcpListToolsCompleted([String: Any]) // "mcp_list_tools.completed" with tools data
   case mcpListToolsFailed(String?) // "mcp_list_tools.failed" with error details
+
+  // Response completion with potential errors
+  case responseDone(status: String, statusDetails: [String: Any]?) // "response.done"
 }