Properly handle API response format

Author: lemonyte

src/contiguity/_response.py

@@ -1,19 +1,37 @@
 from http import HTTPStatus
+from typing import Generic, TypeVar
 
-from msgspec import Struct
+import msgspec
 
+T = TypeVar("T", bound=msgspec.Struct)
 
-class ResponseMetadata(Struct):
+
+class ResponseMetadata(msgspec.Struct):
     id: str
     timestamp: int
     api_version: str
     object: str
 
 
-class BaseResponse(Struct):
+class RawResponse(ResponseMetadata, Generic[T]):
+    data: T
+
+
+class BaseResponse(msgspec.Struct):
     metadata: ResponseMetadata
 
 
 class ErrorResponse(BaseResponse):
     error: str
     status: HTTPStatus
+
+
+def decode_response(content: bytes, /, *, type: type[T]) -> T:
+    raw = msgspec.json.decode(content, type=RawResponse[type])
+    metadata = ResponseMetadata(
+        id=raw.id,
+        timestamp=raw.timestamp,
+        api_version=raw.api_version,
+        object=raw.object,
+    )
+    return msgspec.convert({**msgspec.to_builtins(raw.data), "metadata": metadata}, type=type)

src/contiguity/email.py

@@ -3,10 +3,8 @@
 from http import HTTPStatus
 from typing import overload
 
-import msgspec
-
 from ._product import BaseProduct
-from ._response import BaseResponse, ErrorResponse
+from ._response import BaseResponse, ErrorResponse, decode_response
 
 
 class EmailResponse(BaseResponse):
@@ -83,11 +81,11 @@ def email(  # noqa: PLR0913
         response = self._client.post("/send/email", json=email_payload)
 
         if response.status_code != HTTPStatus.OK:
-            data = msgspec.json.decode(response.content, type=ErrorResponse)
+            data = decode_response(response.content, type=ErrorResponse)
             msg = f"failed to send email. {response.status_code} {data.error}"
             raise ValueError(msg)
 
-        data = msgspec.json.decode(response.content, type=EmailResponse)
+        data = decode_response(response.content, type=EmailResponse)
         if self.debug:
             print(f"successfully sent email to {to}")
 

src/contiguity/otp.py

@@ -3,11 +3,10 @@
 from enum import Enum
 from http import HTTPStatus
 
-import msgspec
 import phonenumbers
 
 from ._product import BaseProduct
-from ._response import BaseResponse, ErrorResponse
+from ._response import BaseResponse, ErrorResponse, decode_response
 
 
 class OTPLanguage(str, Enum):
@@ -82,11 +81,11 @@ def send(
         )
 
         if response.status_code != HTTPStatus.OK:
-            data = msgspec.json.decode(response.content, type=ErrorResponse)
+            data = decode_response(response.content, type=ErrorResponse)
             msg = f"failed to send OTP. {response.status_code} {data.error}"
             raise ValueError(msg)
 
-        data = msgspec.json.decode(response.content, type=OTPSendResponse)
+        data = decode_response(response.content, type=OTPSendResponse)
         if self.debug:
             print(f"successfully sent OTP {data.otp_id} to {to}")
 
@@ -101,11 +100,11 @@ def resend(self, otp_id: str, /) -> OTPResendResponse:
         )
 
         if response.status_code != HTTPStatus.OK:
-            data = msgspec.json.decode(response.content, type=ErrorResponse)
+            data = decode_response(response.content, type=ErrorResponse)
             msg = f"failed to resend OTP. {response.status_code} {data.error}"
             raise ValueError(msg)
 
-        data = msgspec.json.decode(response.content, type=OTPResendResponse)
+        data = decode_response(response.content, type=OTPResendResponse)
         if self.debug:
             print(f"successfully resent OTP {otp_id} with status: {data.resent}")
 
@@ -121,11 +120,11 @@ def verify(self, otp: int | str, /, *, otp_id: str) -> OTPVerifyResponse:
         )
 
         if response.status_code != HTTPStatus.OK:
-            data = msgspec.json.decode(response.content, type=ErrorResponse)
+            data = decode_response(response.content, type=ErrorResponse)
             msg = f"failed to verify OTP. {response.status_code} {data.error}"
             raise ValueError(msg)
 
-        data = msgspec.json.decode(response.content, type=OTPVerifyResponse)
+        data = decode_response(response.content, type=OTPVerifyResponse)
         if self.debug:
             print(f"successfully verified OTP ({otp}) with status: {data.verified}")
 

src/contiguity/text.py

@@ -1,10 +1,9 @@
 from http import HTTPStatus
 
-import msgspec
 import phonenumbers
 
 from ._product import BaseProduct
-from ._response import BaseResponse, ErrorResponse
+from ._response import BaseResponse, ErrorResponse, decode_response
 
 
 class TextResponse(BaseResponse):
@@ -41,10 +40,11 @@ def send(self, *, to: str, message: str) -> TextResponse:
         )
 
         if response.status_code != HTTPStatus.OK:
+            data = decode_response(response.content, type=ErrorResponse)
             msg = f"failed to send message. {response.status_code} {data.error}"
             raise ValueError(msg)
 
-        data = msgspec.json.decode(response.content, type=TextResponse)
+        data = decode_response(response.content, type=TextResponse)
         if self.debug:
             print(f"successfully sent text to {to}")