# NOTE: This file is auto generated by OpenAPI Generator 7.22.0 (https://openapi-generator.tech).
# Do not edit this file manually.

defmodule Spatio.Api.OAuth do
  @moduledoc """
  API calls for all endpoints tagged `OAuth`.
  """

  alias Spatio.Connection
  import Spatio.RequestBuilder

  @doc """
  JSON Web Key Set for id_token verification (RFC 7517).
  The set of public keys RPs use to verify Spatio-issued id_tokens. Cached for 5 minutes at the edge. Always includes the currently-active signing key plus any retired keys that may still be in circulation (id_token TTL is 1 hour + slack). 

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.Jwks.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec get_jwks(Tesla.Env.client, keyword()) :: {:ok, Spatio.Model.Jwks.t} | {:error, Tesla.Env.t}
  def get_jwks(connection, _opts \\ []) do
    request =
      %{}
      |> method(:get)
      |> url("/.well-known/jwks.json")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.Jwks}
    ])
  end

  @doc """
  OAuth 2.1 authorization server metadata (RFC 8414).
  Returns the canonical metadata for the Spatio OAuth 2.1 + OpenID Connect server. Third-party RPs use this to auto-discover endpoint URLs, supported scopes, and signing algorithms.  Identical payload to `/.well-known/openid-configuration` — either path is acceptable; OIDC clients prefer the openid-configuration alias. 

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.DiscoveryDocument.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec get_o_auth_discovery(Tesla.Env.client, keyword()) :: {:ok, Spatio.Model.DiscoveryDocument.t} | {:error, Tesla.Env.t}
  def get_o_auth_discovery(connection, _opts \\ []) do
    request =
      %{}
      |> method(:get)
      |> url("/.well-known/oauth-authorization-server")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.DiscoveryDocument}
    ])
  end

  @doc """
  OpenID Connect Discovery 1.0 metadata.
  Alias of `/.well-known/oauth-authorization-server`. Provided so OIDC client libraries (NextAuth, Auth.js, oidc-client-ts, passport-openidconnect) auto-detect Spatio as an OIDC provider via their `wellKnown` / `discoveryUrl` config field. 

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.DiscoveryDocument.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec get_open_id_configuration(Tesla.Env.client, keyword()) :: {:ok, Spatio.Model.DiscoveryDocument.t} | {:error, Tesla.Env.t}
  def get_open_id_configuration(connection, _opts \\ []) do
    request =
      %{}
      |> method(:get)
      |> url("/.well-known/openid-configuration")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.DiscoveryDocument}
    ])
  end

  @doc """
  OIDC UserInfo (OpenID Connect Core 1.0 §5.3).
  Returns user claims gated by the scopes on the presenting access token. `sub` is always returned; `email`, `name`, etc. require their respective scopes. 

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.UserInfoResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec get_user_info(Tesla.Env.client, keyword()) :: {:ok, nil} | {:ok, Spatio.Model.UserInfoResponse.t} | {:error, Tesla.Env.t}
  def get_user_info(connection, _opts \\ []) do
    request =
      %{}
      |> method(:get)
      |> url("/oauth2/userinfo")
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.UserInfoResponse},
      {401, false}
    ])
  end

  @doc """
  OAuth 2.1 authorization endpoint (RFC 6749 + 7636 PKCE).
  Browser-redirect endpoint. Validates the client + redirect_uri, packs the request into a signed JWT, and 302s the user's browser to the consent UI. The consent UI then POSTs to `/oauth2/authorize/confirm` with the user's decision.  OIDC additions: `scope=openid+profile+email`, `nonce`, `prompt` (none|login|consent), `max_age`. 

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `client_id` (String.t): 
  - `redirect_uri` (Uri): 
  - `response_type` (String.t): 
  - `code_challenge` (String.t): 
  - `code_challenge_method` (String.t): 
  - `opts` (keyword): Optional parameters
    - `:scope` (String.t): 
    - `:state` (String.t): 
    - `:nonce` (String.t): 
    - `:prompt` (String.t): 
    - `:max_age` (integer()): 

  ### Returns

  - `{:ok, nil}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec oauth_authorize(Tesla.Env.client, String.t, Uri, String.t, String.t, String.t, keyword()) :: {:ok, nil} | {:error, Tesla.Env.t}
  def oauth_authorize(connection, client_id, redirect_uri, response_type, code_challenge, code_challenge_method, opts \\ []) do
    optional_params = %{
      :scope => :query,
      :state => :query,
      :nonce => :query,
      :prompt => :query,
      :max_age => :query
    }

    request =
      %{}
      |> method(:get)
      |> url("/oauth2/authorize")
      |> add_param(:query, :client_id, client_id)
      |> add_param(:query, :redirect_uri, redirect_uri)
      |> add_param(:query, :response_type, response_type)
      |> add_param(:query, :code_challenge, code_challenge)
      |> add_param(:query, :code_challenge_method, code_challenge_method)
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {302, false}
    ])
  end

  @doc """
  RFC 7662 token introspection. Accepts both OAuth access tokens and PATs.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `token` (String.t): 
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.IntrospectionResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec oauth_introspect(Tesla.Env.client, String.t, keyword()) :: {:ok, Spatio.Model.IntrospectionResponse.t} | {:error, Tesla.Env.t}
  def oauth_introspect(connection, token, _opts \\ []) do
    request =
      %{}
      |> method(:post)
      |> url("/oauth2/introspect")
      |> add_param(:form, :token, token)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.IntrospectionResponse}
    ])
  end

  @doc """
  RFC 7009 token revocation. Idempotent.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `token` (String.t): 
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, nil}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec oauth_revoke(Tesla.Env.client, String.t, keyword()) :: {:ok, nil} | {:error, Tesla.Env.t}
  def oauth_revoke(connection, token, _opts \\ []) do
    request =
      %{}
      |> method(:post)
      |> url("/oauth2/revoke")
      |> add_param(:form, :token, token)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, false}
    ])
  end

  @doc """
  Exchange authorization code or refresh token for an access token (+ id_token if `openid` scope).

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `grant_type` (String.t): 
  - `opts` (keyword): Optional parameters
    - `:code` (String.t): Required for authorization_code grant.
    - `:code_verifier` (String.t): PKCE verifier — required for authorization_code grant.
    - `:redirect_uri` (Uri): 
    - `:refresh_token` (String.t): Required for refresh_token grant.
    - `:client_id` (String.t): 
    - `:client_secret` (String.t): 

  ### Returns

  - `{:ok, Spatio.Model.TokenResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec oauth_token(Tesla.Env.client, String.t, keyword()) :: {:ok, Spatio.Model.OAuthError.t} | {:ok, Spatio.Model.TokenResponse.t} | {:error, Tesla.Env.t}
  def oauth_token(connection, grant_type, opts \\ []) do
    optional_params = %{
      :code => :form,
      :code_verifier => :form,
      :redirect_uri => :form,
      :refresh_token => :form,
      :client_id => :form,
      :client_secret => :form
    }

    request =
      %{}
      |> method(:post)
      |> url("/oauth2/token")
      |> add_param(:form, :grant_type, grant_type)
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.TokenResponse},
      {400, Spatio.Model.OAuthError}
    ])
  end

  @doc """
  Same as GET /oauth2/userinfo. Provided for clients that send the bearer in the body.

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.UserInfoResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec post_user_info(Tesla.Env.client, keyword()) :: {:ok, Spatio.Model.UserInfoResponse.t} | {:error, Tesla.Env.t}
  def post_user_info(connection, _opts \\ []) do
    request =
      %{}
      |> method(:post)
      |> url("/oauth2/userinfo")
      |> ensure_body()
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, Spatio.Model.UserInfoResponse}
    ])
  end

  @doc """
  Register a new OAuth 2.1 client (RFC 7591 dynamic client registration).
  Returns a fresh `client_id` (and, for confidential clients, `client_secret`) plus a one-time `registration_access_token` the client can use later to update its registration. Public clients (mobile, SPA) MUST use `token_endpoint_auth_method: none` and PKCE.  Rate-limited to 10 registrations per hour per source IP. 

  ### Parameters

  - `connection` (Spatio.Connection): Connection to server
  - `client_registration_request` (ClientRegistrationRequest): 
  - `opts` (keyword): Optional parameters

  ### Returns

  - `{:ok, Spatio.Model.ClientRegistrationResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec register_o_auth_client(Tesla.Env.client, Spatio.Model.ClientRegistrationRequest.t, keyword()) :: {:ok, nil} | {:ok, Spatio.Model.OAuthError.t} | {:ok, Spatio.Model.ClientRegistrationResponse.t} | {:error, Tesla.Env.t}
  def register_o_auth_client(connection, client_registration_request, _opts \\ []) do
    request =
      %{}
      |> method(:post)
      |> url("/oauth2/register")
      |> add_param(:body, :body, client_registration_request)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {201, Spatio.Model.ClientRegistrationResponse},
      {400, Spatio.Model.OAuthError},
      {429, false}
    ])
  end
end