HTTP

magick_mind.http.client

HTTP client for making API requests.

HTTPClient

class HTTPClient()

Async HTTP client wrapper for making authenticated API requests.

Handles:

• Authentication header injection
• Error handling and response parsing
• Retry logic
• Request/response logging

HTTPClient.__init__

def __init__(config: SDKConfig, auth: AuthProvider)

Initialize HTTP client.

Arguments:

• config - SDK configuration
• auth - Authentication provider

HTTPClient.get

async def get(path: str,
              params: Optional[Dict[str, Any]] = None,
              headers: Optional[Dict[str, str]] = None) -> JSONResponse

Make a GET request.

Arguments:

• path - API endpoint path
• params - Query parameters
• headers - Additional headers

Returns:

Response data as dictionary

Raises:

• AuthenticationError - If JWT token is invalid (auto-refreshed if expired)
• ProblemDetailsException - For API errors (4xx, 5xx) following RFC 7807
• ValidationError - For 400 Bad Request with field-level errors
• RateLimitError - For 429 Too Many Requests
• MagickMindError - For unexpected errors or malformed responses

Example:

response = await client.http.get("/v1/magickspaces") print(response['data'])

HTTPClient.post

async def post(path: str,
               json: Optional[Dict[str, Any]] = None,
               headers: Optional[Dict[str, str]] = None) -> JSONResponse

Make a POST request.

Arguments:

• path - API endpoint path
• json - Request body as dictionary
• headers - Additional headers

Returns:

Response data as dictionary

Raises:

• AuthenticationError - If JWT token is invalid (auto-refreshed if expired)
• ProblemDetailsException - For API errors (4xx, 5xx) following RFC 7807
• ValidationError - For 400 Bad Request with field-level validation errors
• RateLimitError - For 429 Too Many Requests
• MagickMindError - For unexpected errors or malformed responses

Example:

response = await client.http.post( ... "/v1/magickmind/chat", ... json={"message": "Hello", "mindspace_id": "mind-123"} ... )

HTTPClient.raw_request

async def raw_request(method: str,
                      path: str,
                      json: Optional[Dict[str, Any]] = None,
                      headers: Optional[Dict[str, str]] = None,
                      use_auth: bool = True) -> httpx.Response

Make a request and return the raw httpx response.

HTTPClient.stream

@asynccontextmanager
async def stream(method: str,
                 path: str,
                 json: Optional[Dict[str, Any]] = None,
                 headers: Optional[Dict[str, str]] = None,
                 use_auth: bool = True) -> AsyncIterator[httpx.Response]

Stream a raw httpx response using this client's base URL and auth.

HTTPClient.put

async def put(path: str,
              json: Optional[Dict[str, Any]] = None,
              headers: Optional[Dict[str, str]] = None) -> JSONResponse

Make a PUT request.

Arguments:

• path - API endpoint path
• json - Request body as dictionary
• headers - Additional headers

Returns:

Response data as dictionary

Raises:

• AuthenticationError - If JWT token is invalid (auto-refreshed if expired)
• ProblemDetailsException - For API errors (4xx, 5xx) following RFC 7807
• ValidationError - For 400 Bad Request with field-level validation errors
• RateLimitError - For 429 Too Many Requests
• MagickMindError - For unexpected errors or malformed responses

HTTPClient.patch

async def patch(path: str,
                json: Optional[Dict[str, Any]] = None,
                headers: Optional[Dict[str, str]] = None) -> JSONResponse

Make a PATCH request.

Arguments:

• path - API endpoint path
• json - Request body as dictionary
• headers - Additional headers

Returns:

Response data as dictionary

Raises:

• AuthenticationError - If JWT token is invalid (auto-refreshed if expired)
• ProblemDetailsException - For API errors (4xx, 5xx) following RFC 7807
• ValidationError - For 400 Bad Request with field-level validation errors
• RateLimitError - For 429 Too Many Requests
• MagickMindError - For unexpected errors or malformed responses

HTTPClient.delete

async def delete(path: str,
                 headers: Optional[Dict[str, str]] = None) -> JSONResponse

Make a DELETE request.

Arguments:

• path - API endpoint path
• headers - Additional headers

Returns:

Response data as dictionary

Raises:

• AuthenticationError - If JWT token is invalid (auto-refreshed if expired)
• ProblemDetailsException - For API errors (4xx, 5xx) following RFC 7807
• ValidationError - For 400 Bad Request with field-level validation errors
• RateLimitError - For 429 Too Many Requests
• MagickMindError - For unexpected errors or malformed responses

HTTPClient.close

async def close() -> None

Close the HTTP client.

HTTPClient.__aenter__

async def __aenter__() -> HTTPClient

Async context manager entry.

HTTPClient.__aexit__

async def __aexit__(exc_type: object, exc_val: object, exc_tb: object) -> None

Async context manager exit.