Documentation example

documentation_example.rb

require_relative 'postman/email_base'
require_relative 'postman/mail_gun_postman'
require_relative 'postman/custom_sms_gateway'

module Janao
  module Postman
    
    # Sets list of allowed email adapters
    EMAIL_ADAPTERS = {
        'MailGun' => MailGunPostman
    }
    
    # Sets list of allowed sms adapters
    SMS_ADAPTERS = {
        'Custom' => CustomSmsGateway
    }
    
    extend self
    
    # Sets configuration object for various adapter
    #
    Configuration = Class.new ActiveSupport::OrderedOptions
    
    # Error classes to be used
    #
    # Raise when Email address not valid
    EmailNotValid = Class.new StandardError
    # Raise when Adapter not configured from the valid list
    AdapterNotValid = Class.new StandardError
    # Raise when Email address not provided
    ToEmailNotProvided = Class.new StandardError
    # Raise when Adapter not specified
    AdapterNotSpecified = Class.new StandardError
    # Raise when expected method not implemented
    PostmanMethodNotImplemented = Class.new NotImplementedError
    # Raise when both sms and email is disabled from the configuration.
    SmsOrEmailShouldBeSwitchedOn = Class.new StandardError
    # Raise when template not provided.
    TemplateNameNotProvided = Class.new StandardError
    # Raise when numbers not provided
    SmsDestinationNotProvided = Class.new ArgumentError
    
    # Sets if engine can also send emails
    mattr_accessor :send_email, default: true
    
    # Sets email adapter to be used, Default: 'MailGun'
    mattr_accessor :email_adapter, default: 'MailGun'
    
    # Sets sms adapter, Default: 'Custom'
    mattr_accessor :sms_adapter, default: 'Custom'
    
    # Sets configuration that allow engine to send sms as well
    mattr_accessor :send_sms, default: true
    
    # Sets sms length to be validated dynamically, default: 160
    mattr_accessor :sms_length, default: 160
    
    # Sets adapter related configurations to be set, Default: Configuration.new
    mattr_accessor :mailer_configuration, default: Configuration.new
    
    # Sets configuration for SMS
    mattr_accessor :sms_configuration, default: Configuration.new
    
    # Sets dynamic token validation for email template, Default: true
    mattr_accessor :validate_template_token, default: true
    
    # Sets template related settings
    mattr_accessor :common_footer, default: nil
    
    # Sets common_header, default: nil
    mattr_accessor :common_header, default: nil
    
    # Sets date format dynamically
    mattr_accessor :date_format, default: '%d-%m-%Y'
    
    # Sets signature, default: nil
    mattr_accessor :signature, default: nil
    
    # Sets copyright_message, default: nil
    mattr_accessor :copyright_message, default: nil
    
    # Sets company_title, default: nil
    mattr_accessor :company_title, default: nil
    
    # Config Janao::Postman to send email and sms notifications
    # Alias method is .setup of .config, you can use both
    #
    # Example:
    #       Janao::Postman.setup do |config|
    #         # Use only to send email?
    #         config.send_email                   = true
    #         config.send_sms                     = true
    #         config.email_adapter                = 'MailGun'
    #         config.sms_adapter                  = 'Custom'
    #         # Optional parameters
    #         config.mailer_configuration.key     = 'Some sort of identification key'
    #         config.mailer_configuration.secret  = 'Don\'t disclose your secret'
    #         config.sms_configuration.username   = 'iirfann'
    #         config.sms_configuration.password   = 'Passw0rd'
    #         config.common_header                = "<h2>Hay Man</h2>"
    #         config.copyright_message            = "Copyright at Your Company @ 2018"
    #       end
    #
    #
    # @return [Janao::Postman] instance
    def config
      yield self
    end
    
    alias_method :setup, :config
    
    # Just use .() to Send notifications!
    # .()
    #
    # The gateway to send message is to call this method
    #
    #   Janao::Postman.({
    #     template_name: 'registration_greetings',
    #     email: {
    #       to: ['[email protected]', '[email protected]']
    #     },
    #     email_data: { full_name: 'Irfan Ahmed', tnx_number: 'HK29874297492842' },
    #     sms_data: { full_name: 'Irfan Ahmed', tnx_number: 'HK29874297492842' },
    #     numbers: ['+8801766678130', '+880197767130']
    #   })
    #
    # @overload call(*args)
    #   @param [Array<String, Hash>] args
    #   @option args [String] :subject email's subject.
    #   @option args [Hash] :email that takes to, cc and bcc keys witht the value of array type
    #   @option args [String] :template_name to load the expected template provided by client
    #   @option args [Hash] :email_data that contains token values of email template
    #   @option args [Boolean] :send_email should be true by configuration
    #   @option args [Boolean] :send_sms should be true or false by configuration
    #   @option args [Hash] :sms_data should contain token values for sms template's token
    #   @option args [Array] :numbers should represents list of numbers sms to be sent
    #
    # @return [Janao::Postman::Result] object that contains messages, error (true/false), backtrace: []
    def call(*args, &block)
      _block = block
      options = args.extract_options!
      
      send_sms      = options.fetch(:send_sms, Janao::Postman.send_sms) || false
      send_email    = options.fetch(:send_email, Janao::Postman.send_email) || false
      template_name = options.fetch(:template_name, (raise TemplateNameNotProvided, 'please provide an template'))
      
      raise SmsOrEmailShouldBeSwitchedOn, 'please switch on at least on medium (email or sms or both)' unless send_email && send_sms
      
      mailer_klass.(template_name, options, _block) if send_email
      
      if send_sms
        numbers    = Array.wrap(options.fetch(:numbers))
        raise SmsDestinationNotProvided, 'Please provide at least one number' if numbers.empty?
        sms_params = options.fetch(:sms_params, {})
        sms_data   = options.fetch(:sms_data, {})
        sms_klass.(template_name, numbers, sms_data, sms_params, _block)
      end
    end
    
    # Define adapter to be used to send sms
    #
    # @return [SmsAdapter]
    def sms_klass
      SMS_ADAPTERS[Janao::Postman.sms_adapter]
    end
    
    # Define adapter to be used to send email
    #
    # @return [MailerKlass]
    def mailer_klass
      EMAIL_ADAPTERS.fetch(
          Postman.email_adapter,
          (raise AdapterNotValid, 'please provide a valid adapter, Example: Mailgun, ActionMailer')
      )
    end
  end
end