mpx

defmodule Mpx.Tables do
  @moduledoc """
  Interact with Ministry Platform's Tables.

  These calls will all need an active token from an authorized user. See `Mpx.Authentication` for details on how to generate a token.

  ## Listing tables:
  This is a rather simple example of getting a list of all the tables the current user token has access too.
  ```
  {:ok, tables} = Mpx.Tables.list_tables(token)
  ```
  You can also filter the list of tables by passing in a search string (use * as a wildcard).
 . ```
  {:ok, tables} = Mpx.Tables.list_tables(token, "Contacts*")
  ```

  ## Querying tables
  Querying tables is rather easy as well.
  ```
  {:ok, records} = Mpx.get_records("Contacts", token)
  ```
  will return all records from the Contacts table (if your token has access).
  To filter the output,
  ```
  {:ok, records} = Mpx.get_records("Contacts", token, "$filter": "Contact_ID=2186211")
  ```
  See `Mpx.Tables.get_records/3` for the full list of options available.


  """
  import Mpx.Http

  @typedoc """
  Specifies the allowed set of options when making a call to get records
  """
  @type get_record_options :: ["$select": String.t,
                               "$filter": String.t,
                               "$orderBy": String.t,
                               "$groupBy": String.t,
                               "$having": String.t,
                               "$top": String.t,
                               "$skip": String.t,
                               "$distint": :true | :false]

  @typedoc """
  Specifies the allowed set of options for a delete call
  """
  @type delete_options :: ["$select": String.t, "$userId": String.t, id: number()]

  @doc """
  Returns the list of tables available to the current users with basic metadata.

  Requires an authentication token and accepts an optional table name pattern
  to be used for searching tables. Wildcards '?' and '*' can be used at any place.
  If parameter is Null or empty then all tables are returned.

  ## Examples

    ```
    {:ok, token} = Mpx.Authentication.authenticate()
    Mpx.Tables.list_tables(token)
    {:ok, [%{"Name" => "Contacts"}, %{"Name" => "Participants"}]}

    {:ok, token} = Mpx.Authentication.authenticate()
    Mpx.Tables.list_tables(token, "contacts")
    {:ok, [%{"Name" => "Contacts"}]}
    ```

  """
  @spec list_tables(String.t, String.t) :: {:ok, list()} | {:error, map()}
  def list_tables(auth_token,  search \\ "") do
    get("tables", auth_token, "$search": search)
  end

  @doc """
  Deletes multiple records from the specified table.

  Expects the table name, a list of ids of records and an auth_token.
  Also accepts an optional keyword list of options:
  ```
  ["$select": "Comma_Seperated,List_Of_Columns,To_Return",
   "$userId": "userIdToPreformOnBehalfOf"]
  ```
  """
  @spec delete_records(String.t, String.t, list(number()), delete_options) :: {:ok, list()} | {:error, any()}
  def delete_records(table, auth_token, ids, opts \\ []) do
    merged_opts = ids
                  |> Enum.map(fn(x) -> {:id, x} end)
                  |> Keyword.merge(opts)
    delete("tables/#{table}", auth_token, merged_opts)
  end

  @doc """
  Returns the list of records from the specified table satisfying the provided search criteria.

  The optional search parameters are:
  ```
  ["$select": "list of columns to be returned",
   "$filter": "filtering expession to select the records to be returned",
   "$orderBy": "list of columns to be sort the result",
   "$groupBy": "list of columns to group and aggregate result by",
   "$having": "expression to filter the aggregated result by",
   "$top": "maximum number of records to be returned. If not specified than 1000 records are returned",
   "$skip": "number of records in the result to be skiped and the rest are returned",
   "$distint": "Flag indicating that only distinct records must be returned"]
  ```

  ## Examples

    ```
    {:ok, token} = Mpx.Authentication.authenticate()
    Mpx.Tables.get_records("Contacts", token)
    {:ok, [%{"Last_Name" => "Smith", "First_Name" => "Mr."}]}

    {:ok, token} = Mpx.Authentication.authenticate()
    Mpx.Tables.get_records("Contacts", token,
                           "$filter": "First_Name=Mr.",
                           "$select": "Last_Name")
    {:ok, [%{"Last_Name" => "Smith"}]}
    ```

  """
  @spec get_records(String.t, String.t, get_record_options) :: {:ok, list()} | {:error, binary()}
  def get_records(table, auth_token, opts \\ []) do
    get("tables/#{table}", auth_token, opts)
  end

  @doc """
  Returns a single record from the specified table by the records primary key value.

  Optionally pass `["$select": "Columns,To_Select"]` option for only a subset of columns.

  ## Examples

    ```
    {:ok, token} = Mpx.Authentication.authenticate()
    Mpx.Tables.get_record("Contacts", 2186211, token)
    {:ok, %{"Last_Name" => "Smith"}}

    {:ok, token} = Mpx.Authentication.authenticate()
    Mpx.Tables.get_record("Contacts", 2186211, token, "$select": "Last_Name, First_Name")
    {:ok, %{"Last_Name" => "Smith", "First_Name" => "Mr."}}
    ```

  """
  @spec get_record(String.t, number(), String.t, ["$select": String.t]) :: {:ok, map()} | {:error, binary()}
  def get_record(table, id, auth_token, opts \\ []) do
    case get("tables/#{table}/#{id}", auth_token, opts) do
      {:ok, [head | tail]} -> {:ok, head}
      {:ok, []} -> {:error, :no_results}
      err -> err
    end
  end
end