litmus-instant 0.1.0

data/fixtures/vcr_cassettes/Litmus_Instant/prefetch_previews/responds_with_an_array_of_the_requested_configurations.yml

@@ -0,0 +1,88 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://<API_KEY>:@instant-api.litmus.com/v1/emails
+    body:
+      encoding: UTF-8
+      string: '{"plain_text":"Hej världen! Kärlek, den svenska kocken."}'
+    headers:
+      Content-Type:
+      - application/json
+      Accept:
+      - application/json
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Server:
+      - nginx
+      Date:
+      - Tue, 06 Oct 2015 10:40:42 GMT
+      Content-Type:
+      - application/json;charset=utf-8
+      Content-Length:
+      - '58'
+      Connection:
+      - keep-alive
+      Strict-Transport-Security:
+      - max-age=3600; includeSubdomains; preload
+      X-Frame-Options:
+      - DENY
+      X-Content-Type-Options:
+      - nosniff
+    body:
+      encoding: UTF-8
+      string: |-
+        {
+          "email_guid": "6c8862e2-b10d-4753-85d8-340c91c0b071"
+        }
+    http_version: 
+  recorded_at: Tue, 06 Oct 2015 10:40:46 GMT
+- request:
+    method: post
+    uri: https://instant-api.litmus.com/v1/emails/6c8862e2-b10d-4753-85d8-340c91c0b071/previews/prefetch
+    body:
+      encoding: UTF-8
+      string: '{"configurations":[{"client":"OL2010","images":"allowed"},{"client":"IPAD","orientation":"vertical"}]}'
+    headers:
+      Content-Type:
+      - application/json
+      Accept:
+      - application/json
+  response:
+    status:
+      code: 202
+      message: Accepted
+    headers:
+      Server:
+      - nginx
+      Date:
+      - Tue, 06 Oct 2015 10:40:43 GMT
+      Content-Type:
+      - application/json;charset=utf-8
+      Content-Length:
+      - '222'
+      Connection:
+      - keep-alive
+    body:
+      encoding: UTF-8
+      string: |-
+        {
+          "configurations": [
+            {
+              "orientation": "vertical",
+              "images": "allowed",
+              "client": "OL2010"
+            },
+            {
+              "orientation": "vertical",
+              "images": "allowed",
+              "client": "IPAD"
+            }
+          ]
+        }
+    http_version: 
+  recorded_at: Tue, 06 Oct 2015 10:40:46 GMT
+recorded_with: VCR 2.9.3

data/lib/litmus/instant.rb

@@ -0,0 +1,216 @@
+require "litmus/instant/version"
+require "httparty"
+require "uri"
+require "cgi"
+
+module Litmus
+  module Instant
+    include HTTParty
+
+    base_uri "https://instant-api.litmus.com/v1"
+
+    headers "Content-Type" => "application/json"
+    headers "Accept"       => "application/json"
+
+    class Error < StandardError; end
+    class ApiError < Error; end
+    class RequestError < ApiError; end
+    class AuthenticationError < ApiError; end
+    class ServiceError < ApiError; end
+    class TimeoutError < ApiError; end
+    class NotFound < ApiError; end
+    class NetworkError < Error; end
+
+    class << self
+      # HTTParty doesn't favour exceptions, we do, so we wrap its methods to
+      # give us what we want
+      %i{get post patch put delete move copy head options}.each do |method|
+        alias_method :"#{method}_without_raise", method
+
+        define_method method do |*args|
+          begin
+            response = send(:"#{method}_without_raise", *args)
+          rescue SocketError, Timeout::Error, Errno::EINVAL, Errno::ECONNRESET,
+                   EOFError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError,
+                   Net::ProtocolError => e
+            raise NetworkError, e.message
+          rescue HTTParty::Error
+            raise Error, e.message
+          end
+          raise_on_failure(response)
+        end
+      end
+    end
+
+    # Get or set your Instant API key
+    # @return [String]
+    def self.api_key(key=nil)
+      if key
+        @key = key
+        self.basic_auth key, ""
+      end
+      @key
+    end
+    singleton_class.send(:alias_method, :api_key=, :api_key)
+
+    # Describe an email’s content and metadata and, in exchange, receive an
+    # +email_guid+ required to capture previews of it
+    #
+    # We intend these objects to be treated as lightweight. Once uploaded,
+    # emails can't be modified. Obtain a new +email_guid+ each time changes need
+    # to be reflected.
+    #
+    # The uploaded email has a limited lifespan. As a result, a new +email_guid+
+    # should be obtained before requesting new previews if more than a day has
+    # passed since the last upload.
+    #
+    # At least one of +:html_text+, +:plain_text+, +:raw_source+ must be
+    # provided.
+    #
+    # @param [Hash] email
+    # @option email [String] :html_text
+    # @option email [String] :plain_text
+    # @option email [String] :subject
+    # @option email [String] :from_address
+    # @option email [String] :from_display_name
+    # @option email [String] :raw_source
+    #   This field provides an alternative approach to defining the email and
+    #   so is only valid in the absence of all the fields above
+    # @option email [String] :end_user_id A unique identifier for your end
+    #   users. When provided, we use this to partition your usage data.
+    #   See https://litmus.com/partners/api/documentation/instant/03-identifying-end-users/
+    # @option email [Array<Hash>]  :configurations
+    #   An array of capture capture configuration hashes
+    #   This allows pre-requesting previews that should be captured as soon as
+    #   possible. This can be a useful performance optimisation.
+    #   See +.prefetch_previews+ for further detail on format.
+    #
+    # @return [Hash] the response containing the +email_guid+ and also
+    #   confirmation of +end_user_id+ and +configurations+ if provided
+    def self.create_email(email)
+      post("/emails", body: email.to_json)
+    end
+
+    # List supported email clients
+    # @return [Array<String>] array of email client names
+    def self.clients
+      get "/clients"
+    end
+
+    # List supported email client configurations
+    # @return [Hash] hash keyed by email client name, values are a Hash with the
+    #   the keys +orientation_options+ and +images_options+
+    def self.client_configurations
+      get "/clients/configurations"
+    end
+
+    # Request a preview
+    #
+    # This triggers the capture of a preview. The method blocks until capture
+    # completes. The response contains URLs for each of the image sizes
+    # available. A further request will be needed to obtain actual image data
+    # from one of the provided URLs.
+    #
+    # @param email_guid [String]
+    # @param client [String]
+    # @param options [Hash]
+    # @option options [String] :images +allowed+ (default) or +blocked+
+    # @option options [String] :orientation +horizontal+ or +vertical+ (default)
+    #
+    # @return [Hash] a hash mapping the available capture sizes to their
+    #   corresponding URLs
+    def self.get_preview(email_guid, client, options = {})
+      query = URI.encode_www_form(options)
+      get "/emails/#{email_guid}/previews/#{client}?#{query}"
+    end
+
+    # Pre-request a set of previews before download
+    #
+    # This method is provided as an optional performance enhancement, typically
+    # useful before embedding a set of previews within a browser, where
+    # connection limits might otherwise delay the start of capture of some
+    # previews.
+    #
+    # The method does not block while capture occurs, a response is returned
+    # immediately.
+    #
+    # Note that should capture failure occur for a preview, it will only be
+    # discovered when the preview is later requested. Request errors, for
+    # instance attempting to prefetch an invalid client, will result raise
+    # normally howver.
+    #
+    # @param email_guid [String]
+    # @param configurations [Array<Hash>]An array of capture capture configurations
+    #   Each configuration Hash must have a +:client+ key, and optional
+    #   +:orientation+ and +images+ keys
+    #
+    # @return [Hash] confirmation of the configurations being captured
+    def self.prefetch_previews(email_guid, configurations)
+      post "/emails/#{email_guid}/previews/prefetch", body: { configurations: configurations }.to_json
+    end
+
+    # Construct a preview image URL ready for download
+    #
+    # The generated URLs can be embedded directly within a client application,
+    # for instance with the +src+ tag of an HTML +img+ tag.
+    #
+    # This is also useful for downloading a capture in a single step, rather
+    # than calling +.get_preview+ then making a follow up request to retrieve
+    # the image data.
+    #
+    # @param [String] email_guid
+    # @param [String] client
+    # @param [Hash] options
+    # @option options [String] :capture_size +full+ (default), +thumb+ or +thumb450+
+    # @option options [String] :images +allowed+ (default) or +blocked+
+    # @option options [String] :orientation +horizontal+ or +vertical+ (default)
+    # @option options [Boolean] :fallback by default errors during capture
+    #   redirect to a fallback image, setting this to +false+ will mean that
+    #   GETs to the resulting URL will receive HTTP error responses instead
+    # @option options [String] :fallback_url a custom fallback image to display
+    #   in case of errors. This must be an absolute URL and have a recognizable
+    #   image extension. Query parameters are not supported. The image should be
+    #   accessible publicly without the need for authentication.
+    #
+    # @return [String] the preview URL, domain sharded by the client name
+    def self.preview_image_url(email_guid, client, options = {})
+      # We'd use Ruby 2.x keyword args here, but it's more useful to preserve
+      # compatibility for anyone stuck with ruby < 2.x
+      capture_size = options.delete(:capture_size) || "full"
+
+      if options.keys.length > 0
+        if options[:fallback_url]
+          options[:fallback_url] = CGI.escape(options[:fallback_url])
+        end
+        query = URI.encode_www_form(options)
+        "#{sharded_base_uri(client)}/emails/#{email_guid}/previews/#{client}/#{capture_size}?#{query}"
+      else
+        "#{sharded_base_uri(client)}/emails/#{email_guid}/previews/#{client}/#{capture_size}"
+      end
+    end
+
+    private
+
+    # This avoids browser per domain connection limits
+    def self.sharded_base_uri(client)
+      base_uri.gsub("://","://#{client}.")
+    end
+
+    def self.raise_on_failure(response)
+      unless response.success?
+        message = response["description"] || ""
+
+        raise AuthenticationError.new(message) if response.code == 401
+        raise RequestError.new(message) if response.code == 400
+        raise NotFound.new(message) if response.code == 404
+        raise TimeoutError.new(message) if response.code == 504
+        raise ServiceError.new(message) if response.code == 500
+
+        # For all other errors
+        raise ApiError.new(message)
+      end
+
+      response
+    end
+  end
+end

data/lib/litmus/instant/version.rb

@@ -0,0 +1,5 @@
+module Litmus
+  module Instant
+    VERSION = "0.1.0"
+  end
+end

data/litmus-instant.gemspec

@@ -0,0 +1,39 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "litmus/instant/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "litmus-instant"
+  spec.version       = Litmus::Instant::VERSION
+  spec.authors       = ["Rahim Packir Saibo"]
+  spec.email         = ["rahim@litmus.com"]
+
+  spec.summary       = %q{Ruby client library for Litmus Instant API}
+  spec.description   = %q{Ruby client library for Litmus Instant API, provides the simplest way to capture instant email previews in real clients from Ruby.}
+  spec.homepage      = "https://github.com/litmus/instant-api-ruby"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  if spec.respond_to?(:metadata)
+    # spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "httparty", "~> 0.13.5"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "guard-rspec"
+  spec.add_development_dependency "webmock"
+  spec.add_development_dependency "vcr"
+  spec.add_development_dependency "rack"
+end

metadata

@@ -0,0 +1,194 @@
+--- !ruby/object:Gem::Specification
+name: litmus-instant
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rahim Packir Saibo
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-03-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.5
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby client library for Litmus Instant API, provides the simplest way
+  to capture instant email previews in real clients from Ruby.
+email:
+- rahim@litmus.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- examples/.ruby-version
+- examples/Gemfile
+- examples/Gemfile.lock
+- examples/README.md
+- examples/email/test-email.html
+- examples/example_batch.rb
+- examples/example_simple.rb
+- fixtures/vcr_cassettes/Litmus_Instant/client_configurations/returns_a_Hash_of_clients_and_their_available_options.yml
+- fixtures/vcr_cassettes/Litmus_Instant/clients/returns_an_array_of_client_names.yml
+- fixtures/vcr_cassettes/Litmus_Instant/create_email/authenticated_with_invalid_email_Hash_raise_a_request_error.yml
+- fixtures/vcr_cassettes/Litmus_Instant/create_email/authenticated_with_valid_email_Hash_optional_end_user_id_is_relayed.yml
+- fixtures/vcr_cassettes/Litmus_Instant/create_email/authenticated_with_valid_email_Hash_prerequest_configurations_is_relayed.yml
+- fixtures/vcr_cassettes/Litmus_Instant/create_email/authenticated_with_valid_email_Hash_response_.yml
+- fixtures/vcr_cassettes/Litmus_Instant/create_email/unauthenticated_raises_an_authentication_error.yml
+- fixtures/vcr_cassettes/Litmus_Instant/get_preview/raises_NotFound_for_an_expired_email_guid.yml
+- fixtures/vcr_cassettes/Litmus_Instant/get_preview/raises_RequestError_for_an_invalid_client.yml
+- fixtures/vcr_cassettes/Litmus_Instant/get_preview/raises_RequestError_for_an_invalid_email_guid.yml
+- fixtures/vcr_cassettes/Litmus_Instant/get_preview/returns_a_Hash_of_the_image_types.yml
+- fixtures/vcr_cassettes/Litmus_Instant/get_preview/supports_optional_capture_configuration.yml
+- fixtures/vcr_cassettes/Litmus_Instant/prefetch_previews/raises_RequestError_for_an_invalid_email_guid.yml
+- fixtures/vcr_cassettes/Litmus_Instant/prefetch_previews/raises_RequestError_if_any_invalid_configurations_are_present.yml
+- fixtures/vcr_cassettes/Litmus_Instant/prefetch_previews/responds_with_an_array_of_the_requested_configurations.yml
+- lib/litmus/instant.rb
+- lib/litmus/instant/version.rb
+- litmus-instant.gemspec
+homepage: https://github.com/litmus/instant-api-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Ruby client library for Litmus Instant API
+test_files: []
+has_rdoc: