Miosa.Client (Miosa v1.0.0)

Copy Markdown View Source

HTTP transport layer for the MIOSA API.

Holds configuration and wraps Req for all request types: JSON API calls, multipart file uploads, binary downloads, and SSE streaming.

Construct a client via Miosa.client/2 rather than using this module directly.

Options

  • :api_key — Required. API key starting with msk_.
  • :base_url — Override the API base URL. Defaults to https://api.miosa.ai/api/v1.
  • :timeout — Request timeout in milliseconds. Defaults to 30_000.
  • :receive_timeout — Receive timeout for long-running requests. Defaults to 60_000.
  • :retry — Whether to retry failed requests. Defaults to false.

Summary

Types

result(type)
t()

Functions

delete(client, path, opts \\ [])

Performs a DELETE request and decodes the JSON response.

get(client, path, opts \\ [])

Performs a GET request and decodes the JSON response.

get_binary(client, path, opts \\ [])

Performs a GET request and returns the raw binary response body.

new(api_key, opts \\ [])

Builds a new Miosa.Client struct.

patch(client, path, body \\ nil, opts \\ [])

Performs a PATCH request with a JSON body and decodes the response.

post(client, path, body \\ nil, opts \\ [])

Performs a POST request with a JSON body and decodes the response.

post_multipart(client, path, parts, opts \\ [])

Performs a multipart POST for file uploads.

put(client, path, body \\ nil, opts \\ [])

Performs a PUT request with a JSON body and decodes the response.

stream_sse(client, path, callback, opts \\ [])

Opens an SSE stream and calls callback for each parsed event.

Types

result(type)

@type result(type) :: {:ok, type} | {:error, Miosa.Error.t()}

t()

@type t() :: %Miosa.Client{
  _req: Req.Request.t(),
  api_key: String.t(),
  base_url: String.t(),
  receive_timeout: pos_integer(),
  retry: boolean(),
  timeout: pos_integer()
}

Functions

delete(client, path, opts \\ [])

@spec delete(t(), String.t(), keyword()) :: result(map())

Performs a DELETE request and decodes the JSON response.

get(client, path, opts \\ [])

@spec get(t(), String.t(), keyword()) :: result(map())

Performs a GET request and decodes the JSON response.

get_binary(client, path, opts \\ [])

@spec get_binary(t(), String.t(), keyword()) :: result(binary())

Performs a GET request and returns the raw binary response body.

Used for downloading files and screenshots.

new(api_key, opts \\ [])

@spec new(
  String.t(),
  keyword()
) :: t()

Builds a new Miosa.Client struct.

Validates the API key format and constructs a base Req request with default headers and options pre-applied.

patch(client, path, body \\ nil, opts \\ [])

@spec patch(t(), String.t(), map() | nil, keyword()) :: result(map())

Performs a PATCH request with a JSON body and decodes the response.

post(client, path, body \\ nil, opts \\ [])

@spec post(t(), String.t(), map() | nil, keyword()) :: result(map())

Performs a POST request with a JSON body and decodes the response.

post_multipart(client, path, parts, opts \\ [])

@spec post_multipart(t(), String.t(), list(), keyword()) :: result(map())

Performs a multipart POST for file uploads.

parts should be a list of {name, value} tuples or {name, value, opts} tuples compatible with Req's :form_multipart option.

put(client, path, body \\ nil, opts \\ [])

@spec put(t(), String.t(), map() | nil, keyword()) :: result(map())

Performs a PUT request with a JSON body and decodes the response.

stream_sse(client, path, callback, opts \\ [])

@spec stream_sse(t(), String.t(), function(), keyword()) ::
  :ok | {:error, Miosa.Error.t()}

Opens an SSE stream and calls callback for each parsed event.

The callback receives {event_type :: String.t(), data :: String.t()} tuples. The stream is consumed until the connection closes or the server sends data: [DONE].

Returns :ok when the stream completes or {:error, reason} on failure.