xend

defmodule Xend do
  @moduledoc """
  Wrapper for Facebook's Send API
  This module defines functions for each type of message supported by the API: text, attachment and sender action.
  
  # Usage
  
  Add xend as a dependency in your `mix.exs`:

    defp deps do
      [
        {:xend, "~> 0.5.0"}
      ]
    end


  
  Add your facebook's page access token to your configuration for xend:
  
    config :xend, 
      fb_page_access_token: System.get_env("FB_PAGE_ACCESS_TOKEN")  

  ## Notification types
  
  `text/3`, `text/4` and `attachment/3` functions receive as a last argument a notification type, which can be: `"REGULAR"`, `"SILENT_PUSH"`, `"NO_PUSH"`. 
  Refer to the [Send API documentation](https://developers.facebook.com/docs/messenger-platform/send-api-reference) for more information on notification types.
  """

  use Xend.HTTP

  @type response :: {integer, any} | any
  @type predefined_replies :: [map]

  @allowed_sender_actions [:typing_on, :typing_off, :mark_seen]

  @doc """
  Send a text message

  ## Example
  
    Xend.text("USER_ID", "Hello World", "REGULAR")
  """
  @spec text(String.t, String.t, String.t) :: response
  def text(recipient_id, text, notification_type) do
    post create_body(%{recipient_id: recipient_id, text: text, notification_type: notification_type})
  end

  @doc """
  Send a text message with predefined replies included aka quick replies.

  ## Example
    
    quick_replies = [%{content_type: "text", title: "Yes", payload: ""}, %{content_type: "text", title: "No", payload: ""}]
    Xend.text("USER_ID", "Do you want ketchup with your order?", quick_replies, "REGULAR")

  See https://developers.facebook.com/docs/messenger-platform/send-api-reference/quick-replies for more information on quick replies
  """
  @spec text(String.t, String.t, predefined_replies, String.t) :: response
  def text(recipient_id, text, quick_replies, notification_type) do
    %{message: message} = body = create_body(%{recipient_id: recipient_id, text: text, notification_type: notification_type})
    message = Map.put(message, :quick_replies, quick_replies)
    post %{body | message: message}
  end

  @doc """
  Send an attachment.

  ## Example
    attachment = %{
      type: "image",
      payload: %{
        url: "https://petersapparel.parseapp.com/img/shirt.png"
      }
    }
    Xend.attachment("USER_ID", attachment, "REGULAR")

  See https://developers.facebook.com/docs/messenger-platform/send-api-reference for more info on attachments
  """
  @spec attachment(String.t, map, String.t) :: response
  def attachment(recipient_id, attachment, notification_type) do
    post create_body(%{recipient_id: recipient_id, attachment: attachment, notification_type: notification_type})
  end
  
  @doc """
  Sends a sender action which can be one of the following:
  
  - mark_seen: marks the message as seen
  - typing_on: triggers typing animation
  - typing_off: stops typing animatioon

  ## Example
  
    Xend.action("USER_ID", :mark_seen)
    Xend.action("USER_ID", :typing_on)
    Xend.action("USER_ID", :typing_off)

  See https://developers.facebook.com/docs/messenger-platform/send-api-reference/sender-actions for more information
  """
  @spec action(String.t, atom) :: response
  def action(recipient_id, action) when action in @allowed_sender_actions do
    post %{
      recipient: %{id: recipient_id},
      sender_action: Atom.to_string(action)
    }
  end

  defp create_body(%{recipient_id: recipient_id, attachment: attachment, notification_type: notification_type}) do
    %{
      recipient: %{id: recipient_id},
      message: %{attachment: attachment},
      notification_type: notification_type
    }
  end

  defp create_body(%{recipient_id: recipient_id, text: text, notification_type: notification_type}) do
    %{
      recipient: %{id: recipient_id},
      message: %{text: text},
      notification_type: notification_type
    }
  end
end