mollie_api

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

defmodule MollieAPI.Api.BalancesAPI do
  @moduledoc """
  API calls for all endpoints tagged `BalancesAPI`.
  """

  alias MollieAPI.Connection
  import MollieAPI.RequestBuilder

  @doc """
  Get balance
  When processing payments with Mollie, we put all pending funds — usually minus Mollie fees — on a balance. Once you have linked a bank account to your Mollie account, we can pay out your balance towards this bank account.  With the Balances API you can retrieve your current balance. The response includes two amounts:  * The *pending amount*. These are payments that have been marked as `paid`, but are not yet available on your balance. * The *available amount*. This is the amount that you can get paid out to your bank account, or use for refunds.  With instant payment methods like iDEAL, payments are moved to the available balance instantly. With slower payment methods, like credit card for example, it can take a few days before the funds are available on your balance. These funds will be shown under the *pending amount* in the meanwhile.

  ### Parameters

  - `connection` (MollieAPI.Connection): Connection to server
  - `balance_id` (String.t): Provide the ID of the related balance.
  - `opts` (keyword): Optional parameters
    - `:testmode` (boolean()): You can enable test mode by setting the `testmode` query parameter to `true`.  Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa.
    - `:"idempotency-key"` (String.t): A unique key to ensure idempotent requests. This key should be a UUID v4 string.

  ### Returns

  - `{:ok, MollieAPI.Model.EntityBalance.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec get_balance(Tesla.Env.client, String.t, keyword()) :: {:ok, MollieAPI.Model.ErrorResponse.t} | {:ok, MollieAPI.Model.EntityBalance.t} | {:error, Tesla.Env.t}
  def get_balance(connection, balance_id, opts \\ []) do
    optional_params = %{
      :testmode => :query,
      :"idempotency-key" => :headers
    }

    request =
      %{}
      |> method(:get)
      |> url("/v2/balances/#{balance_id}")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, MollieAPI.Model.EntityBalance},
      {404, MollieAPI.Model.ErrorResponse},
      {429, MollieAPI.Model.ErrorResponse}
    ])
  end

  @doc """
  Get balance report
  Retrieve a summarized report for all transactions on a given balance within a given timeframe.  The API also provides a detailed report on all 'prepayments' for Mollie fees that were deducted from your balance during the reported period, ahead of your Mollie invoice.  The alias `primary` can be used instead of the balance ID to refer to the organization's primary balance.

  ### Parameters

  - `connection` (MollieAPI.Connection): Connection to server
  - `from` (String.t): The start date of the report, in `YYYY-MM-DD` format. The from date is 'inclusive', and in Central European Time. This means a report with for example `from=2024-01-01` will include transactions from 2024-01-01 0:00:00 CET and onwards.
  - `until` (String.t): The end date of the report, in `YYYY-MM-DD` format. The until date is 'exclusive', and in Central European Time. This means a report with for example `until=2024-02-01` will include transactions up until 2024-01-31 23:59:59 CET.
  - `balance_id` (String.t): Provide the ID of the related balance.
  - `opts` (keyword): Optional parameters
    - `:grouping` (BalanceReportGrouping): You can retrieve reports in two different formats. With the `status-balances` format, transactions are grouped by status (e.g. `pending`, `available`), then by transaction type, and then by other sub-groupings where available (e.g. payment method).  With the `transaction-categories` format, transactions are grouped by transaction type, then by status, and then again by other sub-groupings where available.
    - `:testmode` (boolean()): You can enable test mode by setting the `testmode` query parameter to `true`.  Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa.
    - `:"idempotency-key"` (String.t): A unique key to ensure idempotent requests. This key should be a UUID v4 string.

  ### Returns

  - `{:ok, MollieAPI.Model.EntityBalanceReport.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec get_balance_report(Tesla.Env.client, String.t, String.t, String.t, keyword()) :: {:ok, MollieAPI.Model.ErrorResponse.t} | {:ok, MollieAPI.Model.EntityBalanceReport.t} | {:error, Tesla.Env.t}
  def get_balance_report(connection, from, until, balance_id, opts \\ []) do
    optional_params = %{
      :grouping => :query,
      :testmode => :query,
      :"idempotency-key" => :headers
    }

    request =
      %{}
      |> method(:get)
      |> url("/v2/balances/#{balance_id}/report")
      |> add_param(:query, :from, from)
      |> add_param(:query, :until, until)
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, MollieAPI.Model.EntityBalanceReport},
      {404, MollieAPI.Model.ErrorResponse},
      {422, MollieAPI.Model.ErrorResponse},
      {429, MollieAPI.Model.ErrorResponse}
    ])
  end

  @doc """
  Get primary balance
  Retrieve the primary balance. This is the balance of your account's primary currency, where all payments are settled to by default.  This endpoint is a convenient alias of the [Get balance](get-balance) endpoint.

  ### Parameters

  - `connection` (MollieAPI.Connection): Connection to server
  - `opts` (keyword): Optional parameters
    - `:"idempotency-key"` (String.t): A unique key to ensure idempotent requests. This key should be a UUID v4 string.

  ### Returns

  - `{:ok, MollieAPI.Model.EntityBalance.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec get_primary_balance(Tesla.Env.client, keyword()) :: {:ok, MollieAPI.Model.ErrorResponse.t} | {:ok, MollieAPI.Model.EntityBalance.t} | {:error, Tesla.Env.t}
  def get_primary_balance(connection, opts \\ []) do
    optional_params = %{
      :"idempotency-key" => :headers
    }

    request =
      %{}
      |> method(:get)
      |> url("/v2/balances/primary")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, MollieAPI.Model.EntityBalance},
      {429, MollieAPI.Model.ErrorResponse}
    ])
  end

  @doc """
  List balance transactions
  Retrieve a list of all balance transactions. Transactions include for example payments, refunds, chargebacks, and settlements.  For an aggregated report of these balance transactions, refer to the [Get balance report](get-balance-report) endpoint.  The alias `primary` can be used instead of the balance ID to refer to the organization's primary balance.  The results are paginated.

  ### Parameters

  - `connection` (MollieAPI.Connection): Connection to server
  - `balance_id` (String.t): Provide the ID of the related balance.
  - `opts` (keyword): Optional parameters
    - `:from` (String.t): Provide an ID to start the result set from the item with the given ID and onwards. This allows you to paginate the result set.
    - `:limit` (integer()): The maximum number of items to return. Defaults to 50 items.
    - `:testmode` (boolean()): You can enable test mode by setting the `testmode` query parameter to `true`.  Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa.
    - `:"idempotency-key"` (String.t): A unique key to ensure idempotent requests. This key should be a UUID v4 string.

  ### Returns

  - `{:ok, MollieAPI.Model.ListBalanceTransactions200Response.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec list_balance_transactions(Tesla.Env.client, String.t, keyword()) :: {:ok, MollieAPI.Model.ErrorResponse.t} | {:ok, MollieAPI.Model.ListBalanceTransactions200Response.t} | {:error, Tesla.Env.t}
  def list_balance_transactions(connection, balance_id, opts \\ []) do
    optional_params = %{
      :from => :query,
      :limit => :query,
      :testmode => :query,
      :"idempotency-key" => :headers
    }

    request =
      %{}
      |> method(:get)
      |> url("/v2/balances/#{balance_id}/transactions")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, MollieAPI.Model.ListBalanceTransactions200Response},
      {400, MollieAPI.Model.ErrorResponse},
      {404, MollieAPI.Model.ErrorResponse},
      {429, MollieAPI.Model.ErrorResponse}
    ])
  end

  @doc """
  List balances
  Retrieve a list of the organization's balances, including the primary balance.  The results are paginated.

  ### Parameters

  - `connection` (MollieAPI.Connection): Connection to server
  - `opts` (keyword): Optional parameters
    - `:currency` (String.t): Optionally only return balances with the given currency. For example: `EUR`.
    - `:from` (String.t): Provide an ID to start the result set from the item with the given ID and onwards. This allows you to paginate the result set.
    - `:limit` (integer()): The maximum number of items to return. Defaults to 50 items.
    - `:testmode` (boolean()): You can enable test mode by setting the `testmode` query parameter to `true`.  Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa.
    - `:"idempotency-key"` (String.t): A unique key to ensure idempotent requests. This key should be a UUID v4 string.

  ### Returns

  - `{:ok, MollieAPI.Model.ListBalances200Response.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec list_balances(Tesla.Env.client, keyword()) :: {:ok, MollieAPI.Model.ErrorResponse.t} | {:ok, MollieAPI.Model.ListBalances200Response.t} | {:error, Tesla.Env.t}
  def list_balances(connection, opts \\ []) do
    optional_params = %{
      :currency => :query,
      :from => :query,
      :limit => :query,
      :testmode => :query,
      :"idempotency-key" => :headers
    }

    request =
      %{}
      |> method(:get)
      |> url("/v2/balances")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, MollieAPI.Model.ListBalances200Response},
      {400, MollieAPI.Model.ErrorResponse},
      {404, MollieAPI.Model.ErrorResponse},
      {429, MollieAPI.Model.ErrorResponse}
    ])
  end
end