locomotivecms_coal 1.0.0.pre.alpha.1 → 1.0.0.pre.alpha.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 01f8a9184eef3bba35006a814b36c4f484acc624
-  data.tar.gz: d16af0ab9d5ea263bbc4405a6e5a05cfd397e872
+  metadata.gz: 7a8f142dbb0800706987fe62347716b7d5928b54
+  data.tar.gz: 83488a8289d95c6b88f45ca9f936d16703257de0
 SHA512:
-  metadata.gz: 01baf296fbcdfeb412796d7205090f07cb0c3832da2d26aea73f7b7d0e1ae45abc133290b7b3ae9637d3e0b29544125f43c3bd6c167078a503af0ea9fa378382
-  data.tar.gz: 2ccd232d38455846aaa4d0a26d56d49116608f10b021857440347738437dcc1e7bc19cc4be71c59a49ad1ef3656de2090dbcc30f274917932fd3469802ce079a
+  metadata.gz: 94c6a362f32059241e7980251a914d9973fde88123678ee4a716ac4b63b7473d13c1c2cc389e40808068f29475cd15e1eb0d7bae4a18bcf3a7b31376ff9159f5
+  data.tar.gz: 102af54aebaa85d419c03cbad4fc2416f8236fb362afb0f4ffda122b12d46afafc2e7f7d41ec5bc33b267ae299abcb1312ebb9496cc31a50fae85cff2cc30774

data/.gitignore

@@ -1 +1,2 @@
 coverage/
+pkg/

data/Gemfile

@@ -6,6 +6,8 @@ group :development do
 end
 
 group :test do
+  gem 'rest-client',        '~> 1.8.0'
+
   gem 'rspec',              '~> 3.2.0'
   gem 'json_spec',          '~> 1.1.4'
 

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    locomotivecms_coal (1.0.0.pre.alpha.1)
+    locomotivecms_coal (1.0.0.pre.alpha.2)
       activesupport (~> 4.2.1)
-      unirest (~> 1.1.2)
+      faraday (~> 0.9.1)
+      faraday_middleware (~> 0.9.1)
 
 GEM
   remote: https://rubygems.org/
@@ -31,15 +32,25 @@ GEM
       safe_yaml (~> 1.0.0)
     diff-lcs (1.2.5)
     docile (1.1.5)
+    domain_name (0.5.23)
+      unf (>= 0.0.5, < 1.0.0)
+    faraday (0.9.1)
+      multipart-post (>= 1.2, < 3)
+    faraday_middleware (0.9.1)
+      faraday (>= 0.7.4, < 0.10)
+    http-cookie (1.0.2)
+      domain_name (~> 0.5)
     i18n (0.7.0)
     json (1.8.2)
     json_spec (1.1.4)
       multi_json (~> 1.0)
       rspec (>= 2.0, < 4.0)
     method_source (0.8.2)
-    mime-types (1.25.1)
-    minitest (5.5.1)
+    mime-types (2.4.3)
+    minitest (5.6.1)
     multi_json (1.11.0)
+    multipart-post (2.0.0)
+    netrc (0.10.3)
     pry (0.10.1)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
@@ -48,10 +59,10 @@ GEM
       byebug (~> 4.0)
       pry (~> 0.10)
     rake (10.4.2)
-    rdoc (4.2.0)
-    rest-client (1.6.8)
-      mime-types (~> 1.16)
-      rdoc (>= 2.4.2)
+    rest-client (1.8.0)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 3.0)
+      netrc (~> 0.7)
     rspec (3.2.0)
       rspec-core (~> 3.2.0)
       rspec-expectations (~> 3.2.0)
@@ -79,10 +90,9 @@ GEM
     tins (1.3.5)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
-    unirest (1.1.2)
-      addressable (~> 2.3.5)
-      json (~> 1.8.1)
-      rest-client (~> 1.6.7)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.6)
     vcr (2.9.3)
     webmock (1.9.3)
       addressable (>= 2.2.7)
@@ -99,6 +109,7 @@ DEPENDENCIES
   locomotivecms_coal!
   pry-byebug (~> 3.1.0)
   rake (~> 10.4.2)
+  rest-client (~> 1.8.0)
   rspec (~> 3.2.0)
   vcr
   webmock

data/README.md

@@ -2,9 +2,29 @@
 
 [![Code Climate](https://codeclimate.com/github/locomotivecms/coal/badges/gpa.svg)](https://codeclimate.com/github/locomotivecms/coal) [![Dependency Status](https://gemnasium.com/locomotivecms/coal.svg)](https://gemnasium.com/locomotivecms/coal) [![Build Status](https://travis-ci.org/locomotivecms/coal.svg?branch=master)](https://travis-ci.org/locomotivecms/coal) [![Coverage Status](https://coveralls.io/repos/locomotivecms/coal/badge.svg?branch=master)](https://coveralls.io/r/locomotivecms/coal?branch=master)
 
-The Ruby API Client for LocomotiveCMS.
-
-## Installation [WIP]
+The Ruby API Client for LocomotiveCMS V3 (WIP).
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Authentication](#authentication)
+  - [Resources](#resources)
+      - [MyAccount](#my-account)
+      - [Sites](#sites)
+      - [Pages](#pages)
+      - [Content Types](#content-types)
+      - [Content Entries](#content-entries)
+      - [Snippets](#snippets)
+      - [Theme Assets](#theme-assets)
+      - [Content Assets](#content-assets)
+- [What is missing](#todo)
+- [Contributing](#contributing)
+- [How to write specs](#how-to-write-specs)
+- [Credits](#credits)
+- [License](#license)
+
+## Installation
 
     gem install locomotivecms_coal --pre
 
@@ -12,7 +32,13 @@ The Ruby API Client for LocomotiveCMS.
 
 ### Authentication
 
-    client = Locomotive::Coal::Client.new('http://www.myengine.dev/locomotive/api', { email: <EMAIL>, api_key: <API KEY> })
+    client = Locomotive::Coal::Client.new('http://www.myengine.dev', { email: <EMAIL>, api_key: <API KEY> })
+
+You can get the version of the remote running Engine by calling the following method:
+
+    client.engine_version
+
+*Note:* Coal only supports Engine version **~> 3.0.0**.
 
 ### Resources
 
@@ -23,6 +49,15 @@ The Ruby API Client for LocomotiveCMS.
     my_account = client.my_account.get
     puts my_account.name + " / " + my_account.email
 
+**If not logged in, then it's possible to create your account**
+
+    client = Locomotive::Coal::Client.new('http://www.myengine.dev')
+    client.my_account.create(name: 'John Doe', email: 'john@doe.net', password: 'easyone', password_confirmation: 'easyone')
+
+**Update my account**
+
+    client.my_account.update(name: 'Jane Doe')
+
 #### Sites
 
 **Get all my sites**
@@ -38,6 +73,35 @@ The Ruby API Client for LocomotiveCMS.
 
     my_site = client.sites.destroy(my_site._id)
 
+#### Pages
+
+*Note:* We first need to log in to the site. It can be done by calling the scope_by method of the client instance.
+
+    site = client.sites.by_subdomain('acme')
+    site_client = client.scope_by(site)
+
+**Get the list of pages in English**
+
+    pages = site_client.pages.all(:en)
+
+**Get only the id/fullpath attributes**
+
+    pages = site_client.pages.fullpaths(:en)
+
+It is required when we need the id of an existing page according to its fullpath.
+
+**Create a page**
+
+    page = site_client.pages.create(title: 'About us', slug: 'about-us', parent: 'index', template: 'Locomotive rocks!')
+
+**Update a page in French**
+
+    site_client.pages.update(page._id, { template: 'Locomotive est trop fort!!!' }, :fr)
+
+**Destroy a page**
+
+    site_client.pages.destroy(page._id)
+
 #### Content Types
 
 **Get a content type by its slug**
@@ -51,7 +115,7 @@ The Ruby API Client for LocomotiveCMS.
 
 #### Content Entries
 
-**Get all the first 10 entries filtered by a property (published)**
+**Get the first 10 entries filtered by a property (published)**
 
     articles = site_client.contents.articles.all({ published: true })
 
@@ -64,20 +128,95 @@ The Ruby API Client for LocomotiveCMS.
       page = articles._next_page
     end
 
+*Note:* You can also use the following syntax
+
+    content_type = site_client.contents.projects
+    articles = site_client.content_entries(content_type).all
+
+**Create a content entry**
+
+    first_article = site_client.contents.articles.create(title: 'Hello world')
+
 **Update a content entry**
 
     article = site_client.contents.articles.all.first
     site_client.contents.articles.update(article._id, { title: 'Hello world'})
 
-## TODO
+**Update a content entry in a different locale**
 
-We only implemented a few resources (my_account, sites, content types and content entries) and for some of them, not all the actions have been implemented.
+    # create the article in the default locale
+    article = site_client.contents.articles.create(title: 'Hello world')
 
-Check the issues section of the repository to see what is missing.
+    # then update the title in another locale
+    site_client.contents.articles.update(article._id, { title: 'Bonjour le monde'}, :fr)
 
-## Credits ##
+**Destroy a content entry**
 
-[Christian](https://github.com/cblavier), [Greg](https://github.com/gregKawet) and [Ben](https://github.com/stiiig) from the Cogip/Insert International LTD who brainstormed with me (a very long time) to find this awesome name.
+    site_client.contents.articles.destroy(article._id)
+
+#### Snippets
+
+**Get the list of snippets**
+
+    snippets = site_client.snippets.all
+
+**Create a snippet**
+
+    snippet = site_client.snippets.create(name: 'Header', slug: 'header', template: 'Locomotive rocks!')
+
+    # create a snippet in different locales
+
+    snippet = site_client.snippets.create(name: 'Header', slug: 'header', template: { en: 'Locomotive rocks!', fr: 'Locomotive déchire !' })
+
+**Update a snippet**
+
+    site_client.snippets.update('header', template: 'Locomotive rocks!!!')
+
+**Destroy a snippet**
+
+    site_client.snippets.destroy('header')
+
+#### Theme assets
+
+**Get the list of theme assets**
+
+    assets = site_client.theme_assets.all
+
+**Create a theme asset**
+
+    asset = site_client.theme_assets.create(source: Locomotive::Coal::UploadIO.new('<local path of my image>'), folder: 'images/header')
+
+**Update a theme asset**
+
+    site_client.theme_assets.update(asset._id, source: Locomotive::Coal::UploadIO.new('<local path of my new image>'))
+
+**Destroy a theme asset**
+
+    site_client.theme_assets.destroy(asset._id)
+
+#### Content assets
+
+**Get the list of content assets**
+
+    assets = site_client.content_assets.all
+
+**Create a content asset**
+
+    asset = site_client.content_assets.create(source: Locomotive::Coal::UploadIO.new('<local path of my image>'))
+
+**Update a content asset**
+
+    site_client.content_assets.update(asset._id, source: Locomotive::Coal::UploadIO.new('<local path of my new image>'))
+
+**Destroy a content asset**
+
+    site_client.content_assets.destroy(asset._id)
+
+## What is missing?
+
+We only implemented a few resources (my_account, sites, content types and content entries) and for some of them, not all the actions have been implemented.
+
+Check the issues section of the repository to see what is missing.
 
 ## Contributing
 
@@ -87,6 +226,24 @@ Check the issues section of the repository to see what is missing.
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
 
+## How to write specs
+
+**Engine configuration:**
+
+1. You need to run the last version (master branch) of the [Locomotive engine](https://github.com/locomotivecms/engine).
+2. Pick a different database name to run your Coal specs against.
+3. Run ````bundle exec rake development:bootstrap````
+4. Run the Locomotive server ````bundle exec rails server````
+
+**System configuration:**
+
+- edit your /etc/hosts file (*NIX systems) and add 2 lines
+      127.0.0.0     www.example.com acme.example.com
+
+## Credits
+
+[Christian](https://github.com/cblavier), [Greg](https://github.com/gregKawet) and [Ben](https://github.com/stiiig) from the Cogip/Insert International LTD who brainstormed with me (a very long time) to find this awesome name.
+
 ## License
 
 Copyright (c) 2015 NoCoffee. MIT Licensed, see LICENSE for details.

data/lib/locomotive/coal/client.rb

@@ -2,15 +2,14 @@ module Locomotive::Coal
 
   class Client
 
-    attr_reader :uri, :credentials
+    attr_reader :uri, :credentials, :options
 
-    attr_accessor :scoped_by_site
-
-    def initialize(uri, credentials)
+    def initialize(uri, credentials, options = {})
       if uri.blank? || credentials.blank?
         raise MissingURIOrCredentialsError.new('URI and/or credentials are missing')
       else
-        @uri, @credentials = URI(uri), credentials
+        @options = { path_prefix: 'locomotive' }.merge(options).with_indifferent_access
+        @uri, @credentials = prepare_uri(uri), credentials.with_indifferent_access
       end
     end
 
@@ -19,33 +18,84 @@ module Locomotive::Coal
     end
 
     def my_account
-      @my_account ||= Resources::MyAccount.new(uri, token)
+      @my_account ||= Resources::MyAccount.new(uri, connection)
     end
 
     def sites
-      @sites ||= Resources::Sites.new(uri, token)
+      @sites ||= Resources::Sites.new(uri, connection)
+    end
+
+    def pages
+      @pages ||= Resources::Pages.new(uri, connection)
+    end
+
+    def content_types
+      @content_types ||= Resources::ContentTypes.new(uri, connection)
+    end
+
+    alias :contents :content_types
+
+    def content_entries(content_type)
+      @content_entries ||= {}
+      @content_entries[content_type.slug] ||= Resources::ContentEntries.new(uri, connection, content_type)
+    end
+
+    def content_assets
+      @content_assets ||= Resources::ContentAssets.new(uri, connection)
+    end
+
+    def theme_assets
+      @theme_assets ||= Resources::ThemeAssets.new(uri, connection)
+    end
+
+    def snippets
+      @snippets ||= Resources::Snippets.new(uri, connection)
+    end
+
+    def translations
+      @translations ||= Resources::Translations.new(uri, connection)
     end
 
-    def contents
-      @contents ||= Resources::Contents.new(uri, token)
+    def engine_version
+      @engine_version ||= Resources::EngineVersion.new(uri, connection).version
     end
 
+    alias version engine_version
+
     def scope_by(site)
-      if site.domains.include?(domain)
-        self
-      else
-        new_uri = site.domains.first
-        self.class.new(new_uri, self.credentials).tap do |_client|
-          _client.scoped_by_site = true
-        end
-      end
+      options[:handle] = site.handle
+      self
+    end
+
+    def reset
+      @token = @my_account = @sites = @pages = @content_types = @theme_assets = @content_assets = @translations = nil
+    end
+
+    def ssl?
+      !!self.options[:ssl]
     end
 
     private
 
-    def domain
-      self.uri.to_s =~ /^https?:\/\/([^\/:]+)*/
-      $1
+    def connection
+      _token = credentials[:token] || -> { token }
+      credentials.merge(token: _token, handle: options[:handle])
+    end
+
+    def uri_path
+      [self.options[:path_prefix], 'api', 'v3'].join('/')
+    end
+
+    def prepare_uri(uri)
+      uri = "http://#{uri.to_s}" unless uri.to_s =~ /^https?:\/\//
+
+      URI(uri).tap do |uri|
+        uri.scheme = 'https' if ssl?
+
+        if uri.path == '/' || uri.path.blank?
+          uri.merge!(uri_path)
+        end
+      end
     end
 
   end

data/lib/locomotive/coal/client_v2.rb

@@ -0,0 +1,31 @@
+module Locomotive::Coal
+
+  class ClientV2 < Client
+
+    attr_accessor :scoped_by_site
+
+    def scope_by(site)
+      if site.domains.include?(domain)
+        self
+      else
+        new_uri = site.domains.first
+
+        self.class.new(new_uri, credentials, options).tap do |_client|
+          _client.scoped_by_site = true
+        end
+      end
+    end
+
+    private
+
+    def uri_path(handle = nil)
+      "#{self.options[:path_prefix]}/api"
+    end
+
+    def domain
+      self.uri.host
+    end
+
+  end
+
+end

data/lib/locomotive/coal/error.rb

@@ -5,23 +5,64 @@ module Locomotive::Coal
   #
   class Error < StandardError
 
+    attr_reader :response
+
+    def initialize(response = nil)
+      @response = response
+      super(build_message)
+    end
+
+    def body
+      @response.body || {}
+    end
+
     def self.from_response(response)
-      status = response.code
-      if klass = case status
+      status = response.status
+      if klass = case status.to_i
                   when 401      then Locomotive::Coal::UnauthorizedError
                   when 404      then Locomotive::Coal::UnknownResourceError
+                  when 422      then Locomotive::Coal::InvalidResourceError
                   when 429      then Locomotive::Coal::TooManyRequestsError
-                  when 400..499 then Error
+                  when 500      then Locomotive::Coal::ServerSideError
+                  else Error
                   end
         klass.new(response)
       end
     end
+
+    private
+
+    def build_message
+      @response ? body['error'] : nil
+    end
+
   end
 
-  class MissingURIOrCredentialsError < Error; end
+  class MissingURIOrCredentialsError < StandardError; end
+  class BadRequestError < StandardError; end
   class UnknownResourceError < Error; end
   class TooManyRequestsError < Error; end
   class UnauthorizedError < Error; end
-  class BadRequestError < Error; end
+  class ServerSideError < Error; end
+  class TimeoutError < Error; end
+
+  class InvalidResourceError < Error
+
+    private
+
+    def build_message
+      attributes = body['attributes'].map do |name, errors|
+        if errors.is_a?(Hash)
+          errors.map do |k, _errors|
+            "#{name}.#{k}: #{_errors.join(' + ')}"
+          end
+        else
+          "#{name} #{errors.join(' ')}"
+        end
+      end
+      "#{body['error']}: #{attributes.join(', ')}"
+    end
+
+  end
 
 end

data/lib/locomotive/coal/resources/base.rb

@@ -0,0 +1,57 @@
+require_relative 'concerns/request'
+
+module Locomotive::Coal
+  module Resources
+
+    class Base
+
+      include Concerns::Request
+
+      attr_accessor :uri, :credentials
+
+      def initialize(uri, credentials)
+        @uri, @credentials = uri, credentials
+      end
+
+      def index
+        get(resources_name).map do |attributes|
+          Resource.new(attributes)
+        end
+      end
+
+      alias :all :index
+
+      def create(attributes = {})
+        data = post(resources_name, { resource_name => attributes })
+        Resource.new(data)
+      end
+
+      def update(id, attributes = {})
+        data = put("#{resources_name}/#{id}", { resource_name => attributes })
+        Resource.new(data)
+      end
+
+      def update_with_locale(id, attributes = {}, locale = nil)
+        data = put("#{resources_name}/#{id}", { _locale: locale, resource_name => attributes })
+        Resource.new(data)
+      end
+
+      def destroy(id)
+        data = delete("#{resources_name}/#{id}")
+        Resource.new(data)
+      end
+
+      private
+
+      def resources_name
+        resource_name.pluralize
+      end
+
+      def resource_name
+        self.class.name.demodulize.underscore.singularize
+      end
+
+    end
+
+  end
+end