ExOura.TypeDecoder (ex_oura v2.0.2)

View Source

Decodes HTTP response bodies based on operation type specifications.

This module handles the conversion of raw JSON responses from the Oura API into properly typed Elixir data structures. It supports various type conversions including dates, timestamps, unions, and complex nested structures generated by the OpenAPI code generator.

Key Features

  • Date/DateTime Parsing: Automatically converts ISO8601 date and datetime strings
  • Struct Creation: Builds proper structs from generated OpenAPI client modules
  • Union Type Handling: Resolves union types based on actual data
  • Nested Object Support: Recursively processes nested objects and lists
  • Null Safety: Handles optional/nullable fields gracefully

Type Conversion Rules

  • String dates (YYYY-MM-DD) → Date structs
  • ISO8601 timestamps → DateTime structs
  • Nested objects → Module structs (when available)
  • Lists → Recursively processed lists
  • Union types → Resolved based on data type

Usage

This module is used internally by the ExOura client and typically doesn't need to be called directly. The Client module automatically uses this to decode API responses.

Examples

# Internal usage by Client
operation = %{response: %{200 => {MyModule, :t}}}
{:ok, decoded} = TypeDecoder.decode_response(200, json_body, operation)

Summary

Functions

decode_response(status, body, operation)

Decodes an HTTP response body based on the operation's type specifications.

Functions

decode_response(status, body, operation)

@spec decode_response(status :: pos_integer(), body :: term(), operation :: map()) ::
  {:ok, term()} | {:error, :unable_to_decode}

Decodes an HTTP response body based on the operation's type specifications.

Takes the HTTP status code, response body, and operation metadata to determine the appropriate type conversion and decode the response into proper Elixir data structures.

Parameters

  • status - HTTP status code from the response
  • body - Raw response body (typically parsed JSON)
  • operation - Operation metadata containing response type specifications

Returns

  • {:ok, decoded_data} - Successfully decoded response
  • {:error, :unable_to_decode} - When type information is missing or invalid

Type Resolution

The function looks up the expected response type based on:

  1. The HTTP status code
  2. The operation's response type mapping
  3. Applies appropriate type conversions

Examples

# Decode a successful response
operation = %{response: %{200 => {MyModule, :t}}}
{:ok, result} = decode_response(200, %{field: "value"}, operation)

# Handle unknown response types
{:error, :unable_to_decode} = decode_response(200, body, %{})