[template] add API for the preview template endpoint

Author: Ashu Goel

lib/template.ex

@@ -0,0 +1,47 @@
+defmodule SparkPost.Template do
+  @moduledoc """
+  The SparkPost Template API for working with templates. Use `SparkPost.Template.preview/2` to
+  preview a template.
+
+  Check out the documentation for each function
+  or use the [SparkPost API reference](https://developers.sparkpost.com/api/templates.html) for details.
+
+  Returned by `SparkPost.template.preview/2`.
+    -from
+      -email
+      -name
+    -subject
+    -reply_to
+    -text
+    -html
+    -headers
+  """
+
+  alias SparkPost.{Endpoint, Template}
+
+  @doc """
+  Generate a preview of an existing template.
+
+  ### Parameters
+  - %SparkPost.Content.TemplateRef{} consisting of:
+    - template_id: The string id of the template to retrieve a preview or.
+    - use_draft_template: If true, previews the most recent draft template.
+        If false, previews the most recent published template. If nil,
+        previews the most recently template version period.
+  - substitution_data: k,v map consisting of substituions. See the
+      [SparkPost Substitutions Reference](https://developers.sparkpost.com/api/substitutions-reference.html)
+      for more details.
+  """
+  def preview(%SparkPost.Content.TemplateRef{} = template, substitution_data) do
+    qs = if is_nil(template.use_draft_template) do
+      ""
+    else
+      "?draft=#{template.use_draft_template}"
+    end
+    body = %{substitution_data: substitution_data}
+    :post
+    |> Endpoint.request("/templates/#{template.template_id}/preview#{qs}", body)
+    |> Endpoint.marshal_response(Template.ContentResponse)
+    |> Template.ContentResponse.convert_from_field
+  end
+end

lib/template/content_response.ex

@@ -0,0 +1,31 @@
+defmodule SparkPost.Template.ContentResponse do
+  @moduledoc """
+  The content portion of a response generated when SparkPost receives a Template object.
+
+  See the [SparkPost Template Documentation](https://developers.sparkpost.com/api/templates.html#header-content-attributes)
+  for more details.
+
+  ## Fields
+    - html: HTML content for the email's text/html MIME part
+    - text: Text content for the email's text/plain MIME part
+    - subject: Email subject line
+    - from: a %SparkPost.Address{} object
+    - reply_to: Email address used to compose the email's "Reply-To" header
+    - headers: JSON object container headers other than "Subject", "From", "To" and "Reply-To"
+  """
+
+  defstruct html: nil,
+    text: nil,
+    subject: :required,
+    from: :required,
+    reply_to: nil,
+    headers: nil
+
+  @doc """
+  Convert a raw "from" field into a %SparkPost.Address{} object.
+  """
+  def convert_from_field(%SparkPost.Endpoint.Error{} = response), do: response
+  def convert_from_field(%__MODULE__{} = response) do
+    %{response | from: SparkPost.Address.to_address(response.from)}
+  end
+end

test/data/previewtemplate.json

@@ -0,0 +1,15 @@
+{
+    "results": {
+        "from": {
+            "email": "marketing@bounces.company.example",
+            "name": "Example Company Marketing"
+        },
+        "subject": "Summer deals for Natalie",
+        "reply_to": "Summer deals <summer_deals@company.example>",
+        "text": "Check out these deals Natalie!",
+        "html": "<b>Check out these deals Natalie!</b>",
+        "headers": {
+            "X-Customer-Campaign-ID": "Summer2014"
+        }
+    }
+}

test/data/previewtemplate_simpleemail.json

@@ -0,0 +1,12 @@
+{
+    "results": {
+        "from": "marketing@bounces.company.example",
+        "subject": "Summer deals for Natalie",
+        "reply_to": "Summer deals <summer_deals@company.example>",
+        "text": "Check out these deals Natalie!",
+        "html": "<b>Check out these deals Natalie!</b>",
+        "headers": {
+            "X-Customer-Campaign-ID": "Summer2014"
+        }
+    }
+}

test/template_test.exs

@@ -0,0 +1,83 @@
+defmodule SparkPost.TemplateTest do
+  use ExUnit.Case, async: false
+
+  alias SparkPost.Content.TemplateRef
+  alias SparkPost.{Endpoint, MockServer, Template}
+  alias SparkPost.Template.ContentResponse
+
+  import Mock
+
+  defmodule TestStruct do
+    def basic_template do
+      %TemplateRef{template_id: "TEMPLATE_ID", use_draft_template: nil}
+    end
+
+    def template_with_draft do
+      %TemplateRef{template_id: "TEMPLATE_ID", use_draft_template: true}
+    end
+
+    def substitution_data do
+      %{
+        key1: "value1",
+        key2: "value2"
+      }
+    end
+  end
+
+  describe "preview tests" do
+    test_with_mock "Template.preview succeeds with Template.ContentResponse",
+      HTTPoison, [request: fn (method, url, body, headers, opts) ->
+        assert method == :post
+        # draft not set
+        assert String.ends_with?(url, "preview")
+        fun = MockServer.mk_http_resp(200, MockServer.get_json("previewtemplate"))
+        fun.(method, url, body, headers, opts)
+      end] do
+        resp = Template.preview(TestStruct.basic_template(), TestStruct.substitution_data())
+        assert %ContentResponse{} = resp
+    end
+
+    test_with_mock "Template.preview succeeds with Template.ContentResponse and draft set",
+      HTTPoison, [request: fn (method, url, body, headers, opts) ->
+        assert method == :post
+        assert String.ends_with?(url, "preview?draft=true")
+        fun = MockServer.mk_http_resp(200, MockServer.get_json("previewtemplate"))
+        fun.(method, url, body, headers, opts)
+      end] do
+        resp = Template.preview(TestStruct.template_with_draft(), TestStruct.substitution_data())
+        assert %ContentResponse{} = resp
+    end
+
+    test_with_mock "Template.preview fails with Endpoint.Error", HTTPoison,
+      [request: MockServer.mk_fail] do
+        resp = Template.preview(TestStruct.basic_template(), TestStruct.substitution_data())
+        assert %Endpoint.Error{} = resp
+    end
+
+    test_with_mock "Template.preview unmarshals complex from field correctly", HTTPoison,
+      [request: fn (method, url, body, headers, opts) ->
+        assert method == :post
+        fun = MockServer.mk_http_resp(200, MockServer.get_json("previewtemplate"))
+        fun.(method, url, body, headers, opts)
+      end] do
+        resp = Template.preview(TestStruct.basic_template(), TestStruct.substitution_data())
+        assert %SparkPost.Address{
+          name: "Example Company Marketing",
+          "email": "marketing@bounces.company.example"
+        } == resp.from
+    end
+
+    test_with_mock "Template.preview unmarshals simple from field correctly", HTTPoison,
+      [request: fn (method, url, body, headers, opts) ->
+        assert method == :post
+        fun = MockServer.mk_http_resp(200, MockServer.get_json("previewtemplate_simpleemail"))
+        fun.(method, url, body, headers, opts)
+      end] do
+        resp = Template.preview(TestStruct.basic_template(), TestStruct.substitution_data())
+        assert %SparkPost.Address{
+          name: nil,
+          "email": "marketing@bounces.company.example"
+        } == resp.from
+    end
+  end
+end