Adds a super useful mix task: gringotts.new

* Generates a barebones implementation
* Also generates docs dynamically,
  - If no required_keys are supplied when the task is run, the docs do
not contain an empty table.
  - Otherwise, the table and config examples include the keys.

lib/mix/new.ex

@@ -0,0 +1,97 @@
+defmodule Mix.Tasks.Gringotts.New do
+  @shortdoc """
+  Generates a barebones implementation for a gateway.
+  """
+
+  @moduledoc """
+  Generates a barebones implementation for a gateway.
+
+  It expects the (brand) name of the gateway as argument. This will not
+  necessarily be the module name, but we recommend the name be capitalized.
+
+  mix gringotts.new NAME [-m, --module MODULE] [--url URL]
+
+  A barebones implementation of the gateway will be created along with skeleton
+  mock and integration tests in `lib/gringotts/gateways/`. The command will
+  prompt for the module name, and other metadata.
+
+  ## Options
+
+  > ***Tip!***
+  > You can supply the extra arguments to `gringotts.new` to skip (some of) the
+  > prompts.
+
+  * `-m` `--module` - The module name for the Gateway.
+  * `--url` - The homepage of the gateway.
+
+  ## Examples
+
+      mix gringotts.new foobar
+
+  The prompts for this will be:
+  MODULE = `Foobar`
+  URL = `https://www.foobar.com`
+  REQUIRED_KEYS = []
+  """
+
+  use Mix.Task
+  import Mix.Generator
+
+  @long_msg ~s{
+Comma separated list of required configuration keys:
+(This can be skipped by hitting `Enter`)
+> }
+
+  def run(args) do
+    {key_list, [name], []} =
+      OptionParser.parse(
+        args,
+        switches: [module: :string, url: :string],
+        aliases: [m: :module]
+      )
+
+    Mix.Shell.IO.info("Generating barebones implementation for #{name}.")
+    Mix.Shell.IO.info("Hit enter to select the suggestion.")
+
+    module_name =
+      case Keyword.fetch(key_list, :module) do
+        :error -> prompt_with_suggestion("\nModule name", String.capitalize(name))
+        {:ok, mod_name} -> mod_name
+      end
+
+    url =
+      case Keyword.fetch(key_list, :url) do
+        :error -> prompt_with_suggestion("\nHomepage URL", "https://www.#{String.Casing.downcase(name)}.com")
+        {:ok, url} -> url
+      end
+
+    required_keys =
+      case Mix.Shell.IO.prompt(@long_msg) |> String.trim do
+        "" -> []
+        keys -> String.split(keys, ",") |> Enum.map(&(String.trim(&1))) |>  Enum.map(&(String.to_atom(&1)))
+      end
+
+    bindings = [
+      gateway: name,
+      gateway_module: module_name,
+      gateway_underscore: Macro.underscore(name),
+      required_config_keys: required_keys,
+      gateway_url: url
+    ]
+
+    if (Mix.Shell.IO.yes? "\nDoes this look good?\n#{inspect(bindings, pretty: true)}\n>") do
+      gateway = EEx.eval_file("templates/gateway.eex", bindings)
+      # mock = ""
+      # integration = ""
+      create_file("lib/gringotts/gateways/#{bindings[:gateway_underscore]}.ex", gateway)
+    else
+      Mix.Shell.IO.info("Doing nothing, bye!")
+    end
+  end
+
+  defp prompt_with_suggestion(message, suggestion) do
+    decorated_message = "#{message} [#{suggestion}]"
+    response = Mix.Shell.IO.prompt(decorated_message) |> String.trim
+    if response == "", do: suggestion, else: response
+  end
+end

templates/gateway.eex

@@ -0,0 +1,275 @@
+defmodule Gringotts.Gateways.<%= gateway_module %> do
+  @moduledoc """
+  [<%= gateway %>][home] gateway implementation.
+
+  ## Instructions!
+
+  ***This is an example `moduledoc`, and suggests some items that should be
+  documented in here.***
+
+  The quotation boxes like the one below will guide you in writing excellent
+  documentation for your gateway. All our gateways are documented in this manner
+  and we aim to keep our docs as consistent with each other as possible.
+  **Please read them and do as they suggest**. Feel free to add or skip sections
+  though.
+
+  If you'd like to make edits to the template docs, they exist at
+  `templates/gateway.eex`. We encourage you to make corrections and open a PR
+  and tag it with the label `template`.
+
+  ***Actual docs begin below this line!***
+
+  --------------------------------------------------------------------------------
+
+  > List features that have been implemented, and what "actions" they map to as
+  > per the <%= gateway %> gateway docs.
+  > A table suits really well for this.
+
+  ## Optional or extra parameters
+
+  Most `Gringotts` API calls accept an optional `Keyword` list `opts` to supply
+  optional arguments for transactions with the gateway.
+
+  > List all available (ie, those that will be supported by this module) keys, a
+  > description of their function/role and whether they have been implemented
+  > and tested.
+  > A table suits really well for this.
+
+  ## Registering your <%= gateway %> account at `Gringotts`
+
+  Explain how to make an account with the gateway and show how to put the
+  `required_keys` (like authentication info) to the configuration.
+  <%= if required_config_keys != [] do %>
+  > Here's how the secrets map to the required configuration parameters for <%= gateway %>:
+  > 
+  > | Config parameter | <%= gateway %> secret   |
+  > | -------          | ----           |
+  <%= for key <- required_config_keys do %>> | `<%= inspect(key) %>`     | **<%= Macro.camelize("#{key}") %>**  |
+  <% end %><% end %>
+  > Your Application config<%= if required_config_keys != [] do %> **must include the `<%= inspect(required_config_keys) %>` field(s)** and<% end %> would look
+  > something like this:
+  > 
+  >     config :gringotts, Gringotts.Gateways.<%= gateway_module %>,
+  >         adapter: Gringotts.Gateways.<%= gateway_module %><%= if required_config_keys != [] do %>,<% end %>
+  <%= for key <- required_config_keys do %>>         <%= "#{key}" %>: "your_secret_<%= "#{key}" %>"
+  <% end %>
+
+  ## Scope of this module
+
+  > It's unlikely that your first iteration will support all features of the
+  > gateway, so list down those items that are missing.
+
+  ## Supported currencies and countries
+
+  > It's enough if you just add a link to the gateway's docs or FAQ that provide
+  > info about this.
+
+  ## Following the examples
+
+  1. First, set up a sample application and configure it to work with MONEI.
+  - You could do that from scratch by following our [Getting Started][gs] guide.
+      - To save you time, we recommend [cloning our example
+      repo][example] that gives you a pre-configured sample app ready-to-go.
+          + You could use the same config or update it the with your "secrets"
+          as described [above](#module-registering-your-monei-account-at-<%=
+          gateway %>).
+
+  2. Run an `iex` session with `iex -S mix` and add some variable bindings and
+  aliases to it (to save some time):
+  ```
+  iex> alias Gringotts.{Response, CreditCard, Gateways.<%= gateway_module %>}
+  iex> card = %CreditCard{first_name: "Jo",
+                          last_name: "Doe",
+                          number: "4200000000000000",
+                          year: 2099, month: 12,
+                          verification_code: "123", brand: "VISA"}
+  ```
+
+  > Add any other frequently used bindings up here.
+
+  We'll be using these in the examples below.
+
+  [gs]: https://github.com/aviabird/gringotts/wiki/
+  [home]: <%= gateway_url %>
+  [example]: https://github.com/aviabird/gringotts_example
+  """
+
+  # The Base module has the (abstract) public API, and some utility
+  # implementations.  
+  use Gringotts.Gateways.Base
+
+  # The Adapter module provides the `validate_config/1`
+  # Add the keys that must be present in the Application config in the
+  # `required_config` list
+  use Gringotts.Adapter, required_config: <%= inspect(required_config_keys) %>
+
+  import Poison, only: [decode: 1]
+
+  alias Gringotts.{Money,
+                   CreditCard,
+                   Response}
+
+  @doc """
+  Performs a (pre) Authorize operation.
+
+  The authorization validates the `card` details with the banking network,
+  places a hold on the transaction `amount` in the customer’s issuing bank.
+
+  > ** You could perhaps:**
+  > 1. describe what are the important fields in the Response struct
+  > 2. mention what a merchant can do with these important fields (ex:
+  > `capture/3`, etc.)
+
+  ## Note
+
+  > If there's anything noteworthy about this operation, it comes here.
+
+  ## Example
+
+  > A barebones example using the bindings you've suggested in the `moduledoc`.
+  """
+  @spec authorize(Money.t(), CreditCard.t(), keyword) :: {:ok | :error, Response}
+  def authorize(amount, card = %CreditCard{}, opts) do
+    # commit(args, ...)
+  end
+
+  @doc """
+  Captures a pre-authorized `amount`.
+
+  `amount` is transferred to the merchant account by <%= gateway %> used in the
+  pre-authorization referenced by `payment_id`.
+
+  ## Note
+
+  > If there's anything noteworthy about this operation, it comes here.
+  > For example, does the gateway support partial, multiple captures?
+
+  ## Example
+
+  > A barebones example using the bindings you've suggested in the `moduledoc`.
+  """
+  @spec capture(Money.t, String.t(), keyword) :: {:ok | :error, Response}
+  def capture(amount, payment_id, opts) do
+    # commit(args, ...)
+  end
+
+  @doc """
+  Transfers `amount` from the customer to the merchant.
+
+  <%= gateway %> attempts to process a purchase on behalf of the customer, by
+  debiting `amount` from the customer's account by charging the customer's
+  `card`.
+
+  ## Note
+
+  > If there's anything noteworthy about this operation, it comes here.
+
+  ## Example
+
+  > A barebones example using the bindings you've suggested in the `moduledoc`.
+  """
+  @spec purchase(Money.t, CreditCard.t(), keyword) :: {:ok | :error, Response}
+  def purchase(amount, card = %CreditCard{}, opts) do
+    # commit(args, ...)
+  end
+
+  @doc """
+  Voids the referenced payment.
+
+  This method attempts a reversal of a previous transaction referenced by
+  `payment_id`.
+
+  > As a consequence, the customer will never see any booking on his statement.
+
+  ## Note
+
+  > Which transactions can be voided?
+  > Is there a limited time window within which a void can be perfomed?
+
+  ## Example
+
+  > A barebones example using the bindings you've suggested in the `moduledoc`.
+  """
+  @spec void(String.t(), keyword) :: {:ok | :error, Response}
+  def void(payment_id, opts) do
+    # commit(args, ...)
+  end
+
+  @doc """
+  Refunds the `amount` to the customer's account with reference to a prior transfer.
+
+  > Refunds are allowed on which kinds of "prior" transactions?
+
+  ## Note
+
+  > The end customer will usually see two bookings/records on his statement. Is
+  > that true for <%= gateway %>?
+  > Is there a limited time window within which a void can be perfomed?
+
+  ## Example
+
+  > A barebones example using the bindings you've suggested in the `moduledoc`.
+  """
+  @spec refund(Money.t, String.t(), keyword) :: {:ok | :error, Response}
+  def refund(amount, <<payment_id::bytes-size(32)>>, opts) do
+    # commit(args, ...)
+  end
+
+  @doc """
+  Stores the payment-source data for later use.
+
+  > This usually enable "One Click" and/or "Recurring Payments"
+
+  ## Note
+
+  > If there's anything noteworthy about this operation, it comes here.
+
+  ## Example
+
+  > A barebones example using the bindings you've suggested in the `moduledoc`.
+  """
+  @spec store(CreditCard.t(), keyword) :: {:ok | :error, Response}
+  def store(%CreditCard{} = card, opts) do
+    # commit(args, ...)
+  end
+
+  @doc """
+  Removes card or payment info that was previously `store/2`d
+
+  Deletes previously stored payment-source data.
+
+  ## Note
+
+  > If there's anything noteworthy about this operation, it comes here.
+
+  ## Example
+
+  > A barebones example using the bindings you've suggested in the `moduledoc`.
+  """
+  @spec unstore(String.t(), keyword) :: {:ok | :error, Response}
+  def unstore(<<registrationId::bytes-size(32)>>, opts) do
+    # commit(args, ...)
+  end
+
+  ###############################################################################
+  #                                PRIVATE METHODS                              #
+  ###############################################################################
+
+  # Makes the request to <%= gateway %>'s network.
+  # For consistency with other gateway implementations, make your (final)
+  # network request in here, and parse it using another private method called
+  # `respond`.
+  @spec commit(_) :: {:ok | :error, Response}
+  defp commit(_) do
+    # resp = HTTPoison.request(args, ...)
+    # respond(resp, ...)
+  end
+
+  # Parses <%= gateway %>'s response and returns a `Gringotts.Response` struct
+  # in a `:ok`, `:error` tuple.
+  @spec respond(term) :: {:ok | :error, Response}
+  defp respond(<%= gateway_underscore %>_response)
+  defp respond({:ok, %{status_code: 200, body: body}}), do: "something"
+  defp respond({:ok, %{status_code: status_code, body: body}}), do: "something"
+  defp respond({:error, %HTTPoison.Error{} = error}), do: "something"
+end