optidash 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 28b445eb3b610f52877cc3ecdde81aa8b6d92dfd88de615f5ceada2ea99729e3
+  data.tar.gz: b433e816bf1eef3a07d062b4f75515bf7a3d88a583cf33ba91a55d3a035b5458
+SHA512:
+  metadata.gz: '053489a1e64b5e6f2a958d2ce98e1d5577a06ee622df557077505b9fcaf7411b9acdcc0260757c4416a122b5ed18405c6c7e512f7f27352100102c3f147eedff'
+  data.tar.gz: c82c266fffb1523d8b4cca16b7442f2fa6d1eb66a2e08e249695c1844b1789d211630e302174be7c8119bd512e1503467cc952359c0b248f9c27bae0367ed7e6

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.idea/*
+.ruby-version
+
+# rspec failure tracking
+.rspec_status

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Optidash UG <support@optidash.ai> (https://optidash.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,101 @@
+<p align="center"><a href="https://optidash.ai"><img src="media/logotype.png" alt="Optidash" width="143" height="45"/></a></p>
+
+<p align="center">
+Optidash is a modern, AI-powered image optimization and processing API.<br>We will drastically speed-up your websites and save you money on bandwidth and storage.
+</p>
+
+---
+<p align="center">
+<strong>The official Ruby integration for the Optidash API.</strong><br>
+<br>
+<img src="https://img.shields.io/gem/v/optidash?style=flat&color=success"/>
+<img src="https://img.shields.io/snyk/vulnerabilities/github/optidash-ai/optidash-ruby?style=flat&color=success"/>
+<img src="https://img.shields.io/github/issues-raw/optidash-ai/optidash-ruby?style=flat&color=success"/>
+<img src="https://img.shields.io/github/license/optidash-ai/optidash-ruby?style=flat&color=success"/>
+<img src="https://img.shields.io/twitter/follow/optidashAI?label=Follow%20Us&style=flat&color=success&logo=twitter"/>
+</p>
+
+---
+
+### Documentation
+See the [Optidash API docs](https://docs.optidash.ai/).
+
+### Installation
+```bash
+$ gem install optidash
+```
+
+### Quick examples
+Optidash API enables you to provide your images for optimization and processing in two ways - by uploading them directly to the API ([Image Upload](https://docs.optidash.ai/requests/image-upload)) or by providing a publicly available image URL ([Image Fetch](https://docs.optidash.ai/requests/image-fetch)).
+
+You may also choose your preferred [response method](https://docs.optidash.ai/introduction#choosing-response-method-and-format) on a per-request basis. By default, the Optidash API will return a [JSON response](https://docs.optidash.ai/responses/json-response-format) with rich metadata pertaining to input and output images. Alternatively, you can use [binary responses](https://docs.optidash.ai/responses/binary-responses). When enabled, the API will respond with a full binary representation of the resulting (output) image. This Ruby integration exposes two convenience methods for interacting with binary responses: `.toFile()` and `.toBuffer()`.
+
+#### Image upload
+Here is a quick example of uploading a local file for processing. It calls `.toJSON()` at a final step and instructs the API to return a JSON response.
+
+```ruby
+require "optidash"
+
+# Pass your Optidash API Key to the constructor
+opti = Optidash.new("your-api-key")
+
+# Upload an image from disk, resize it to 100 x 75,
+# automatically enhance, and adjust sharpness parameter.
+# You'll find the full JSON metadata within the `meta` variable
+err, meta = (
+    opti
+        .upload("path/to/input.jpg")
+        .optimize(
+            compression: "medium"
+        )
+        .resize(
+            width: 100,
+            height: 75
+        )
+        .auto(
+            enhance: true
+        )
+        .adjust(
+            unsharp: 10
+        )
+        .to_json()
+)
+
+abort(err) if err
+```
+
+#### Image fetch
+If you already have your source visuals publicly available online, we recommend using Image Fetch by default. That way you only have to send a JSON payload containing image URL and processing steps. This method is also much faster than uploading a full binary representation of the image.
+
+```ruby
+require "optidash"
+
+# Pass your Optidash API Key to the constructor
+opti = Optidash.new("your-api-key")
+
+# Provide a publicly available image URL with `.fetch()` method,
+# apply Gaussian blur using highly optimized PNG as the output format.
+# We'll also use `.toFile()` method and stream the output image to disk
+err, meta = (
+    opti
+        .fetch("https://www.website.com/image.jpg")
+        .optimize(
+            compression: "medium"
+        )
+        .filter(
+            blur: (
+                mode: "gaussian",
+                value: 10
+            }
+        )
+        .output(
+            format: "png"
+        )
+        .to_file("path/to/output.png")
+)
+
+abort(err) if err
+```
+
+### License
+This software is distributed under the MIT License. See the [LICENSE](LICENSE) file for more information.

data/lib/optidash.rb

@@ -0,0 +1,19 @@
+require "json"
+require "rest-client"
+require "uri"
+require "optidash/version"
+require "optidash/errors"
+require "optidash/request"
+require "optidash/response"
+require "optidash/client"
+
+module Optidash
+
+    ##
+    # Making Client constructor public
+    # to avoid Optidash::Client.new invocation
+
+    def self.new(*args)
+        Client.new(*args)
+    end
+end

data/lib/optidash/client.rb

@@ -0,0 +1,132 @@
+module Optidash
+    ##
+    # Main Client class, responsible for entire interaction with the API
+
+    class Client
+        def initialize(api_key)
+            @api_key = api_key
+        end
+
+        ##
+        # Prepares Fetch request
+        # @param url [String] web location of a file we wan't to transform via api
+
+        def fetch(url)
+            validate_request :fetch
+
+            # initiating the request
+            @request = Optidash::Request::Fetch.new(@api_key, @proxy)
+
+            # and preparing data for the request
+            @request.data[:url] = url
+            self
+        end
+
+
+        ##
+        # Prepares Upload request
+        # @param path [String] local file path
+
+        def upload(path)
+            validate_request :upload
+
+            # initiating the request
+            @request = Optidash::Request::Upload.new(@api_key, path, @proxy)
+            self
+        end
+
+
+        ##
+        # Returns response containing only JSON metadata
+
+        def to_json
+            @request.perform
+        end
+
+
+        ##
+        # Returns response containing JSON metadata and saves received binary file
+        # @param path [String] file destination
+
+        def to_file(path)
+            if path.nil?
+                raise Optidash::Errors::NoPathProvided, "No save path provided"
+            end
+
+            validate_binary_operations
+            @request.perform(binary: true, save_path: path)
+        end
+
+
+        ##
+        # Returns response containing JSON metadata and binary file buffer
+
+        def to_buffer
+            validate_binary_operations
+            @request.perform(binary: true)
+        end
+
+        ##
+        # Sets request proxy
+
+        def proxy(url = nil)
+            return self if url.nil?
+            validate_url(url)
+            # adding proxy if request instance already exists
+            @request ? @request.proxy = url : @proxy = url
+            self
+        end
+
+
+        ##
+        # Meta programmed operation methods - every single one of them does
+        # the same thing: adds operation to be performed along with its params
+        # to the request data
+
+        %i(optimize adjust auto border crop mask output padding resize response scale store filter watermark webhook cdn flip).each do |method|
+            define_method method do |value = {}|
+                return self if value.empty? || !value.respond_to?(:merge)
+                @request.data[method] = value
+                self
+            end
+        end
+
+        private
+
+
+        ##
+        # Validates if we can perform request operation, i.e. if fetch was called
+        # upload should throw an exception and the other way around. So we don't
+        # chain two types of requests
+        #
+        # @param type [Symbol] request type which we want to perform
+
+        def validate_request(type)
+            return if @request.nil? || @request.type == type
+            raise Optidash::Errors::RequestTypeConflict.new(@request.type, type)
+        end
+
+
+        ##
+        # Validates if particular operations are valid for binary responses.
+
+        def validate_binary_operations
+            if @request.data[:webhook]
+                raise Optidash::Errors::OperationNotSupported, "Binary responses are not supported when using Webhooks"
+            end
+
+            if @request.data[:store]
+                raise Optidash::Errors::OperationNotSupported, "Binary responses are not supported when using External Storage"
+            end
+        end
+
+
+        ##
+        # Validates proxy url
+
+        def validate_url(url)
+            return if url =~ /\A#{URI::regexp(['http', 'https'])}\z/
+            raise Optidash::Errors::InvalidProxyUrl, "Proxy url is not valid"
+        end
+    end
+end

data/lib/optidash/errors.rb

@@ -0,0 +1,17 @@
+module Optidash
+
+    ##
+    # Handling errors and app exceptions
+
+    class Errors
+        class RequestTypeConflict < StandardError
+            def initialize(type1, type2)
+                super("current type: #{type1}, attempted: #{type2}")
+            end
+        end
+
+        class NoPathProvided < StandardError; end
+        class OperationNotSupported < StandardError; end
+        class InvalidProxyUrl < StandardError; end
+    end
+end

data/lib/optidash/request.rb

@@ -0,0 +1,134 @@
+module Optidash
+
+    ##
+    # Types of request along with their slightly differing implementations
+
+    class Request
+
+        ##
+        # Base class.
+        # Should be inherited by Fetch and Upload classes.
+
+        class Base
+            attr_reader :type
+            attr_accessor :data
+            attr_accessor :proxy
+
+            API_URL = "https://api.optidash.ai/1.0"
+
+
+            ##
+            # Constructor. Passing api key for authentication
+
+            def initialize(key, proxy = nil)
+
+                ##
+                # Setting initial options for the request
+
+                @options = {
+                    user: key,
+                    password: "",
+                    method: :post,
+                    url: "#{API_URL}/#{@type}",
+                    ssl_ca_file: File.dirname(__FILE__) + '/../data/cacert.pem'
+                }
+
+                @proxy = proxy
+
+                ##
+                # Request data, which will be sent do API server
+
+                @data = {}
+            end
+
+
+            ##
+            # Performs actual request, sending entire data set options:
+            # - binary [Boolean] indicates whether request should return binary response or not
+            # - save_path [String|NilClass] save location for binary file, if needed
+
+            def perform(binary: false, save_path: nil)
+                @data.merge!(response: { mode: "binary" }) if binary
+
+                Optidash::Response.new(
+                    RestClient::Request.execute(@options.merge(
+                        payload: request_data,
+                        headers: headers(binary: binary),
+                        proxy: proxy
+                    )),
+                    save_path: save_path
+                ).data
+            rescue RestClient::ExceptionWithResponse => e
+                Optidash::Response.new(e.response).data
+            end
+
+            private
+
+
+            ##
+            # Prepares request headers, appending x-optidash-binary header if necessary.
+
+            def headers(binary: false)
+                @headers ||= {}
+                @headers["x-optidash-binary"] = 1 if binary
+                @headers
+            end
+        end
+
+
+        ##
+        # Responsible for handling Fetch requests
+
+        class Fetch < Base
+            def initialize(key)
+                @type = :fetch
+                super(key)
+            end
+
+            ##
+            # Returns fetch request data, which is a simple JSON
+
+            def request_data
+                @data.to_json
+            end
+
+            private
+
+            def headers(binary: false)
+                @headers ||= { content_type: :json }
+                super
+            end
+        end
+
+
+        ##
+        # Responsible for handling Upload requests
+
+        class Upload < Base
+            def initialize(key, upload_path, proxy = nil)
+                @type = :upload
+                @upload_path = upload_path
+                super(key, proxy)
+            end
+
+            def perform(binary: false, save_path: nil)
+                unless File.exist?(@upload_path)
+                    return "Input file #{@upload_path} does not exist", nil, nil
+                end
+                super
+            end
+
+
+            ##
+            # Returns upload request data. Multipart containing uploaded file
+            # and operations performed on it
+
+            def request_data
+                {
+                    file: File.new(@upload_path, "rb"),
+                    data: @data.to_json
+                }
+            end
+        end
+    end
+end

data/lib/optidash/response.rb

@@ -0,0 +1,68 @@
+module Optidash
+
+    ##
+    # Builds an object containing response data
+
+    class Response
+        def initialize(object, save_path: nil)
+            @object = object
+            @save_path = save_path
+            fetch_metadata
+            return unless @error.nil?
+
+            binary_response if binary?
+        end
+
+        def data
+            result = [@error, @metadata]
+            result << @file if binary? && @save_path.nil? && @file
+            result
+        end
+
+        private
+
+        def binary?
+            !@object.headers[:x_optidash_meta].nil?
+        end
+
+
+        ##
+        # Extracts the metadata either from the response body
+        # or X-Optidash-Meta header if the binary response was in use
+
+        def fetch_metadata
+            data = JSON.parse(@object.headers[:x_optidash_metadata] || @object.body)
+
+            if data["success"]
+                @metadata = data
+            else
+                @error = data["message"]
+            end
+        rescue JSON::ParserError
+            @error = "Unable to parse JSON response from "
+            @error += (binary? ? "X-Optidash-Meta header" : "the Optidash Image API")
+        end
+
+
+        ##
+        # Handles binary response and
+        # saves the file or stores it as a buffer
+
+        def binary_response
+            return save_file if @save_path
+            @file = @object.body
+        end
+
+
+        ##
+        # Saves binary response to disk
+
+        def save_file
+            @file = File.open(@save_path, "wb")
+            @file.write(@object.body)
+            @file.close
+        rescue
+            @error = "Unable to save resulting image at `#{@save_path}` location"
+        end
+    end
+end

data/lib/optidash/version.rb

@@ -0,0 +1,3 @@
+module Optidash
+    VERSION = "1.0.0"
+end

data/optidash.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "optidash"
+
+Gem::Specification.new do |spec|
+    spec.name = "optidash"
+    spec.version = Optidash::VERSION
+    spec.summary = "Official Ruby integration for Optidash API"
+    spec.description = "Optidash: AI-powered image optimization and processing API. We will drastically speed-up your websites and save you money on bandwidth and storage."
+    spec.author = ["Optidash UG"]
+    spec.email = ["support@optidash.com"]
+    spec.homepage = "https://optidash.ai"
+    spec.license = "MIT"
+
+    spec.files = `git ls-files -z`.split("\x0")
+    spec.require_paths = ['lib']
+
+    spec.add_development_dependency 'bundler', '~> 2.0'
+    spec.add_development_dependency 'rake', '~> 10.0'
+
+    spec.add_dependency 'json', '~> 2.0.3'
+    spec.add_dependency 'rest-client', '~> 2.0.1'
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: optidash
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Optidash UG
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-06-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.3
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+description: 'Optidash: AI-powered image optimization and processing API. We will
+  drastically speed-up your websites and save you money on bandwidth and storage.'
+email:
+- support@optidash.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- lib/data/cacert.pem
+- lib/optidash.rb
+- lib/optidash/client.rb
+- lib/optidash/errors.rb
+- lib/optidash/request.rb
+- lib/optidash/response.rb
+- lib/optidash/version.rb
+- media/logotype.png
+- optidash.gemspec
+homepage: https://optidash.ai
+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: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Official Ruby integration for Optidash API
+test_files: []