Kino.Qx.Client (Kino.Qx v0.3.0)

Copy Markdown View Source

HTTP client for the snippet-browsing slice of the Qx Portal API at /api/v1.

Wraps Req so the snippet Smart Cell never touches HTTP details directly. Maps the documented error shapes to plain tuples the cell can pattern-match on.

Hardware-execution endpoints (/api/v1/transpile) live in Qx.Hardware.Portal upstream — kino_qx delegates through Kino.Qx.run!/2 rather than calling them directly.

All functions take a config map:

%{
  token: "qx_live_...",
  base_url: "https://qxportal.dev"
}

Error mapping

HTTPReturned
200 OK{:ok, decoded_data}
401{:error, :unauthorized}
404{:error, :not_found}
429 + retry-after header{:error, {:rate_limited, secs}}
Other 4xx/5xx{:error, {:http, status, body}}
Network / Req exception{:error, {:network, reason}}

Summary

Types

config()

Configuration map for every client call.

identity()

The shape returned by /api/v1/me.

snippet()

Full snippet as returned by /api/v1/snippets/:id.

snippet_summary()

Single snippet summary as returned by /api/v1/snippets.

Functions

get_snippet(config, id)

Returns one snippet with bodies.

list_snippets(config)

Returns the caller's snippets, newest first. List view (no bodies).

me(config)

Confirms a token is valid and returns the authenticated identity.

Types

config()

@type config() :: %{token: String.t(), base_url: String.t()}

Configuration map for every client call.

identity()

@type identity() :: %{email: String.t(), role: String.t(), api_key_name: String.t()}

The shape returned by /api/v1/me.

snippet()

@type snippet() :: %{
  id: integer(),
  name: String.t(),
  visibility: String.t(),
  share_url: String.t() | nil,
  qasm_content: String.t(),
  elixir_content: String.t(),
  inserted_at: String.t(),
  updated_at: String.t()
}

Full snippet as returned by /api/v1/snippets/:id.

snippet_summary()

@type snippet_summary() :: %{
  id: integer(),
  name: String.t(),
  visibility: String.t(),
  share_url: String.t() | nil,
  inserted_at: String.t(),
  updated_at: String.t()
}

Single snippet summary as returned by /api/v1/snippets.

Functions

get_snippet(config, id)

@spec get_snippet(config(), integer() | String.t()) ::
  {:ok, snippet()} | {:error, term()}

Returns one snippet with bodies.

list_snippets(config)

@spec list_snippets(config()) :: {:ok, [snippet_summary()]} | {:error, term()}

Returns the caller's snippets, newest first. List view (no bodies).

me(config)

@spec me(config()) :: {:ok, identity()} | {:error, term()}

Confirms a token is valid and returns the authenticated identity.