Mints Ruby SDK

This is a library to connect apps built on ruby to Mints.Cloud

Installation

Add gem to the Gemfile

gem 'mints'

Usage

Using Mints Public API

mints_pub = Mints::Pub.new(mints_url, api_key)
mints_pub.get_stories

Using Mints Contact API

mints_contact = Mints::Contact.new(mints_url, api_key)
mints_contact.login(email, password)
mints_contact.me

Using Mints User API

mints_user = Mints::User.new(mints_url, api_key)
mints_user.login(email, password)
mints_user.get_contacts

Using Mints User API by Service account

# Usually the api_key and the session token are the same, you can go to the service accounts section
# from your CXF instance and generate your service account api key  
mints_service_account = Mints::User.new(mints_url, api_key, api_key)
mints_service_account.get_contacts

Generate mints files

This command will generate the mints_config.yml.erb file, API controlles and routes to have available the mints endpoints

rails generate mints_files

Contact tracking usage

Your app controller needs to be inherited from Mints::BaseController

# application_controller.rb

class ApplicationController < Mints::BaseController
end

This heritance will make the following class variables available:

Variable	Description
@host	Host defined in mints_config.yml.erb file
@api_key	API key defined in mints_config.yml.erb file
@mints_pub	An already instanced public client
@contact_token	A token used by mints to identify the contact
@visit_id	An identifier of the visit registered
@mints_contact	An already instanced contact client (not usable until call the contact login method)

And the following controller methods:

Method	Parameters	Return value	Description
mints_contact_signed_in?	none	boolean	Indicates if the contact has an active session
mints_contact_login	email, password	void	Starts a contact session
mints_contact_logout	none	void	Ends a contact session
mints_contact_magic_link_login	hash, redirect_in_error	void	Starts a contact session in mints.cloud and set a session cookie

Admin controller usage

If want to have a private section where only a mints user can acces and use the private user api is needed to inherit from the AdminBaseController.

# admin_controller.rb

class AdminController < Mints::AdminBaseController
end

This heritance will make the following class variables available:

Variable	Description
@host	Host defined in mints_config.yml.erb file
@api_key	API key defined in mints_config.yml.erb file
@mints_user	An already instanced user client (not usable until call the user login method)
@mints_service_account	An already instanced service_account client

And the following controller methods:

Method	Parameters	Return value	Description
mints_user_login	email, password	void	Starts a user session
mints_user_logout	none	void	Ends a user session
mints_user_signed_in?	none	Boolean	Indicates if the user has an active session
mints_user_magic_link_login	hash	void	Starts a user session in mints.cloud and set a session cookie

Mints config file

The mints.config.yml file allows to set the CXF instance to which the implementation will access, it can add the host, api key for CXF, in addition to setting the cache rules with redis, if you want to add a url to cache , you should add it to the groups array and set the cache time.

  # Mints connection configuration
  mints:
    host: http://your_host_goes_here.com
    api_key: your_mints_api_key_goes_here
    mints_slug: slug_id #save id and token in redis
  redis_cache:
    use_cache: boolean_value_to_enable_and_disable_cache
    redis_host: your_redis_server_host
    redis_port: your_redis_server_port
    redis_db: your_redis_database
    groups:
      - urls:
          - group_of_urls
        time: time_that_will_be_applied_to_urls_in_seconds
  sdk:
    debug: false
    # Timeout is specified in seconds
    default_http_timeout: 30 # Allows setting a default timeout for all HTTP calls.
    get_http_timeout: 30 # Allows setting a default timeout for all GET calls.
    post_http_timeout: 30 # Allows setting a default timeout for all POST calls.
    put_http_timeout: 30 # Allows setting a default timeout for all PUT calls.
    delete_http_timeout: 30 # Allows setting a default timeout for all DELETE calls.

To enable sdk debugging you can change the variable debug. Finally, to configure the sharing of cookies between domains, you can configure the "iframe cookies", where you establish how long the cookie will have, if it is activated and the domains to share cookies (to have this functionality, we recommend the use of the template).

  # Mints connection configuration
  sdk:
    debug: false
  cookies_iframe:
    activated: boolean_value_to_enable_and_disable_cookies_iframe
    expire_time: expire_time_of_cookies_iframe_in_hours
    hosts:
      - array_of_host_to_send_cookies

Override default clients

If you want other clients for admin/base controller, you need to specify them with the "define_mints_clients" method

Example:

# admin_controller.rb

class AdminController < Mints::AdminBaseController
  def define_mints_clients
    %w[contact user pub service_account]
  end
end

Override default timeouts

If you want specific timeouts per instance, you can define mints_sdk_timeouts_config

Example:

# admin_controller.rb

class AdminController < Mints::AdminBaseController
  def mints_sdk_timeouts_config
    {
      default: 30,
      get: 50,
      post: 40,
      put: 30,
      delete: 10
    }
  end
end

Error catching

The SDK provides different errors that are identified according to the response provided by CXF, the errors can be 404, 401, 422, 500, etc. To rescue these errors, it is done as follows:

# Example 1
begin
  @mints_pub.client.raw('/invalid-url')
rescue => Mints::Errors::ResourceNotFoundException
  puts "Error 404"
end

# Example 2

begin
  response = @mints_contact.register(data)
rescue Mints::Errors::ValidationException => e
  response = e.to_h
  # This will return a Hash with the information needed to debug
  # Example:
  {
    :client => sdk_instance,
    # Client instance
    # @host = "https://your_cxf_instance",
    # @api_key = current_api_key,
    # @session_token = current_session_token,
    # @contact_token_id = current_contact_token_id,
    # @visit_id = current_visit_id,
    # @debug = current_debug_flag,
    # @scope = current_scope,
    # @base_url = current_base_url
    :title => "Request failed with status 422",
    :detail => "Unprocessable Entity",
    :http_status => 422,
    :response => { "email" => ["The email has already been taken."] },
    :errors => ["The email has already been taken."]
  }
end

The current errors are:

Error	Status	Full error name
AccessDeniedException	401	Mints::Errors::AccessDeniedException
ResourceNotFoundException	404	Mints::Errors::ResourceNotFoundException
MethodNotAllowedException	405	Mints::Errors::MethodNotAllowedException
ValidationException	422	Mints::Errors::ValidationException
InternalServerException	500	Mints::Errors::InternalServerException

Mints::Pub

Mints::Pub::Config
Mints::Pub::Content
Mints::Pub::Ecommerce
- Mints::Pub::Ecommerce::Locations
- Mints::Pub::Ecommerce::Orders

Mints::Contact

Mints::Contact::Config
- Mints::Contact::Config::Appointments
Mints::Contact::Content
- Mints::Contact::Content::Conversations
Mints::Contact::Ecommerce

Mints::User

Mints::Threads

Mints::MakeMultipleRequest

mints

Runtime