built.io 0.1

data/README.md

@@ -0,0 +1,64 @@
+# built.io
+
+built.io is a Backend-as-a-Service. This is the ruby SDK providing convenient
+wrappers for working with built.io.
+
+## Getting Started
+
+Call the `init` method on `Built` to initialize the SDK with your
+application's api_key:
+
+```ruby
+Built.init :application_api_key => "<your api key>"
+```
+
+## Objects
+
+### Create an object
+
+```ruby
+obj = Built::Object.new("people")
+
+obj["name"] = "James"
+obj["age"]  = 32
+
+obj.save
+```
+
+### Update an existing object
+
+If you already have objects from a query, just set the attributes and save:
+
+```ruby
+obj["age"] = 43
+obj.save
+```
+
+If you just have the object's `uid`, set it first:
+
+```ruby
+obj.uid = "bltMyU1d"
+obj["age"] = 43
+obj.save
+```
+
+### Delete an object
+
+```ruby
+obj.destroy
+```
+
+## Querying objects
+
+```ruby
+query = Query.new("people")
+query
+  .containedIn("name", ["James"])
+  .greaterThan("age", 30)
+  .include_count
+
+result = query.exec
+
+puts result.objects[0]
+puts result.count
+```

data/lib/built.rb

@@ -0,0 +1,68 @@
+require "i18n"
+require "httmultiparty"
+
+module Built
+  class << self
+    # singleton http client
+    # @api private
+    @@client = nil
+
+    # Initialize the SDK
+    # @raise [BuiltError]
+    # @param [Hash] options Options
+    # @option options [String] :application_api_key Your app's api_key. Required.
+    # @option options [String] :master_key Your app's master_key
+    # @option options [String] :authtoken A user's authtoken
+    # @option options [String] :host built.io API host (defaults to https://api.built.io)
+    # @option options [String] :version built.io version delimiter (v1, v2, etc)
+    def init(options)
+      options ||= {}
+
+      host        = options[:host]    || API_URI
+      version     = options[:version] || API_VERSION
+      master_key  = options[:master_key]
+      api_key     = options[:application_api_key]
+      authtoken   = options[:authtoken]
+
+      if Util.blank?(api_key)
+        raise BuiltError, I18n.t(
+          "required_parameter", {:param => "application_api_key"})
+      end
+      
+      # create the client
+      @@client = Client.new({
+        host:                 host,
+        version:              version,
+        application_api_key:  api_key,
+        master_key:           master_key,
+        authtoken:            authtoken
+      })
+    end
+
+    # Get the singleton client
+    # @api private
+    def client
+      if !@@client
+        raise BuiltError, I18n.t("not_initialized")
+      end
+
+      @@client
+    end
+
+    # @api private
+    def root
+      File.expand_path '..', __FILE__
+    end
+  end
+end
+
+require "built/constants"
+require "built/i18n"
+require "built/util"
+require "built/error"
+require "built/client"
+require "built/timestamps"
+require "built/application"
+require "built/class"
+require "built/object"
+require "built/query"

data/lib/built/application.rb

@@ -0,0 +1,43 @@
+module Built
+  class Application < Hash
+    include Built::Timestamps
+
+    # Get the uid of this application
+    def uid
+      self["uid"]
+    end
+
+    # Get the name of this application
+    def name
+      self["name"]
+    end
+
+    # Get the api_key of this application
+    def api_key
+      self["api_key"]
+    end
+
+    private
+
+    def to_s
+      "#<Built::Application uid=#{uid}, api_key=#{api_key}>"
+    end
+
+    class << self
+      # Get the application you are working with
+      # @return [Application]
+      def get
+        new.merge!(
+          Built.client.request(uri)
+            .parsed_response["application"]
+        )
+      end
+
+      private
+
+      def uri
+        "/applications/myapp" # no longer require a valid uid to get the application
+      end
+    end
+  end
+end

data/lib/built/class.rb

@@ -0,0 +1,55 @@
+module Built
+  # Built::Class provides the schema and provides grouping for 
+  # different classes of objects.
+  class Class < Hash
+    include Built::Timestamps
+
+    # Get the uid for this class
+    def uid
+      self["uid"]
+    end
+
+    # Get the title for this class
+    def title
+      self["title"]
+    end
+
+    # Is this an inbuilt class, provided by built.io?
+    # @return [Boolean]
+    def inbuilt_class?
+      self["inbuilt_class"] == true
+    end
+
+    private
+
+    def to_s
+      "#<Built::Class uid=#{self["uid"]}, title=#{self["title"]}>"
+    end
+
+    class << self
+      # Get all classes from built. Returns an array of classes.
+      # @raise Built::BuiltAPIError
+      # @return [Array] classes An array of classes
+      def get_all
+        Built.client.request(uri)
+          .parsed_response["classes"].map {|o| new.merge!(o)}
+      end
+
+      # Get a single class by its uid
+      # @raise Built::BuiltAPIError
+      # @param [String] uid The uid of the class
+      # @return [Class] class An instance of Built::Class
+      def get(uid)
+        new.merge!(
+          Built.client.request(uri(uid))
+            .parsed_response["class"]
+        )
+      end
+
+      # @api private
+      def uri(class_uid=nil)
+        class_uid ? "/classes/#{class_uid}" : "/classes"
+      end
+    end
+  end
+end

data/lib/built/client.rb

@@ -0,0 +1,46 @@
+module Built
+  class Client
+    include HTTMultiParty
+
+    def initialize(options={})
+      @api_key    = options[:application_api_key]
+      @master_key = options[:master_key]
+      @host       = options[:host]
+      @version    = options[:version]
+      @authtoken  = options[:authtoken]
+
+      # set the base uri
+      self.class.base_uri @version ? [@host, @version].join('/') : @host
+    end
+
+    # set the authtoken
+    def authtoken=(authtoken)
+      @authtoken = authtoken
+    end
+
+    # perform a regular request
+    def request(uri, method=:get, body=nil, query=nil, additionalHeaders={})
+      options             = {}
+      options[:query]     = query if query
+      options[:body]      = body.to_json if body
+
+      options[:headers]   = {
+        "application_api_key" => @api_key,
+        "Content-Type"        => "application/json"
+      }
+
+      options[:headers][:authtoken]   = @authtoken if @authtoken
+      options[:headers][:master_key]  = @master_key if @master_key
+      options[:headers].merge!(additionalHeaders)
+
+      response = self.class.send(method, uri, options)
+
+      if ![200, 201, 204].include?(response.code)
+        # error, throw it
+        raise BuiltAPIError.new(response.parsed_response)
+      end
+
+      response
+    end
+  end
+end

data/lib/built/constants.rb

@@ -0,0 +1,4 @@
+# constants
+API_URI     = "https://api.built.io"
+# we no longer need version strings
+API_VERSION = nil

data/lib/built/error.rb

@@ -0,0 +1,30 @@
+module Built
+  # Errors thrown by the library on invalid input
+  class BuiltError < StandardError
+  end
+
+  # Errors thrown by the built.io API
+  class BuiltAPIError < BuiltError
+    attr_accessor :error_code
+    attr_accessor :error
+    attr_accessor :error_message
+
+    def initialize(response)
+      @response = response
+
+      if @response
+        @error_code     = response["error_code"]
+        @error          = response["error"]
+        @error_message  = response["error_message"]
+      end
+
+      super("#{@error_code}: #{@error_message}")
+    end
+
+    private
+
+    def to_s
+      @error_message || super
+    end
+  end 
+end

data/lib/built/i18n.rb

@@ -0,0 +1,3 @@
+I18n.load_path += [File.join(Built.root, "locales", "en.yml")]
+I18n.enforce_available_locales = false
+I18n.default_locale = "en"

data/lib/built/object.rb

@@ -0,0 +1,137 @@
+module Built
+  # Built::Object is the unit of data in built.io
+  class Object < Hash
+    include Built::Timestamps
+
+    # Get the uid for this object
+    def uid
+      self["uid"]
+    end
+
+    # Set the uid for this object
+    # @param [String] uid A valid object uid
+    def uid=(uid)
+      self["uid"] = uid
+    end
+
+    # Fetch the latest instance of this object from built
+    # @raise BuiltError If the uid is not set
+    # @return [Object] self
+    def fetch
+      if !uid
+        # uid is not set
+        raise BuiltError, I18n.t("objects.uid_not_set")
+      end
+
+      self.merge!(
+        Built.client.request(uri)
+          .parsed_response["object"]
+      )
+
+      self
+    end
+
+    # Save / persist the object to built.io
+    # @param [Hash] options Options
+    # @option options [Boolean] :timeless Perform a timeless update
+    # @option options [Boolean] :draft Save the object as draft
+    # @raise BuiltAPIError
+    # @return [Object] self
+    def save(options={})
+      if is_new?
+        # create
+        self.merge!(
+          Built.client.request(uri, :post, wrap)
+            .parsed_response["object"]
+        )
+      else
+        headers = {}
+
+        headers[:timeless] = true if options[:timeless]
+
+        if options[:draft]
+          self["published"] = false
+        end
+
+        # update
+        self.merge!(
+          Built.client.request(uri, :put, wrap, nil, headers)
+            .parsed_response["object"]
+        )
+      end
+    end
+
+    # Delete this object
+    # @raise BuiltError If the uid is not set
+    # @return [Object] self
+    def destroy
+      if !uid
+        # uid is not set
+        raise BuiltError, I18n.t("objects.uid_not_set")
+      end
+
+      Built.client.request(uri, :delete)
+
+      self.clear
+
+      self
+    end
+
+    # Get the class in which this object belongs
+    # @return [Class] class
+    def get_class
+      Built::Class.get(@class_uid)
+    end
+
+
+    # Is this a new, unsaved object?
+    # @return [Boolean]
+    def is_new?
+      Util.blank?(self["uid"])
+    end
+
+    # Initialize a new object
+    # @param [String] class_uid The uid of the class to which this object belongs
+    # @param [Hash] data Data to initialize the object with
+    def initialize(class_uid, data=nil)
+      if !class_uid
+        raise BuiltError, I18n.t("objects.class_uid")
+      end
+
+      @class_uid  = class_uid
+
+      if data
+        self.merge!(data)
+      end
+
+      self
+    end
+
+    private
+
+    def uri
+      class_uri = Built::Class.uri(@class_uid)
+
+      uid ? 
+        [class_uri, "objects/#{uid}"].join("/") : 
+        [class_uri, "objects"].join("/")
+    end
+
+    def wrap
+      {"object" => self}
+    end
+
+    def to_s
+      "#<Built::Object uid=#{self["uid"]}, class_uid=#{@class_uid}>"
+    end
+
+    class << self
+      # @api private
+      def uri(class_uid)
+        class_uri = Built::Class.uri(class_uid)
+
+        [class_uri, "objects"].join("/")
+      end
+    end
+  end
+end

data/lib/built/query.rb

@@ -0,0 +1,285 @@
+module Built
+  # Perform a query on objects of a class
+  class Query
+    attr_accessor :params
+
+    # Create a new query
+    # @param [String] class_uid The uid of the class for querying
+    # @example
+    #   query = Query.new("people")
+    # 
+    #   query
+    #     .containedIn("name", ["James"])
+    #     .greaterThan("age", 30)
+    #     .include_count
+    # 
+    #   result = query.exec
+    # 
+    #   puts result.objects[0]
+    #   puts result.count
+    def initialize(class_uid=nil)
+      @class_uid  = class_uid
+      @params     = {
+        "query" => {}
+      }
+    end
+
+    # Where given key matches value
+    # @param [String] key The key on which to search
+    # @param [Object] value The value with which to match
+    # @return [Query] self
+    def where(key, value)
+      @params["query"][key] = value
+
+      self
+    end
+
+    # To check that the key has a value greater than the one specified
+    # @param [String] key The key
+    # @param [Object] value The value
+    # @return [Query] self
+    def greater_than(key, value)
+      @params["query"][key] = {"$gt" => value}
+
+      self
+    end
+
+    # To check that the key has a value greater than OR equaling the one specified
+    # @param [String] key The key
+    # @param [Object] value The value
+    # @return [Query] self
+    def greater_than_equal(key, value)
+      @params["query"][key] = {"$gte" => value}
+
+      self
+    end
+
+    # To check that the key has a value less than the one specified
+    # @param [String] key The key
+    # @param [Object] value The value
+    # @return [Query] self
+    def less_than(key, value)
+      @params["query"][key] = {"$lt" => value}
+
+      self
+    end
+
+    # To check that the key has a value less than OR equaling the one specified
+    # @param [String] key The key
+    # @param [Object] value The value
+    # @return [Query] self
+    def less_than_equal(key, value)
+      @params["query"][key] = {"$lte" => value}
+
+      self
+    end
+
+    # To check that the key has a value not equaling the one specified
+    # @param [String] key The key
+    # @param [Object] value The value
+    # @return [Query] self
+    def not_equal(key, value)
+      @params["query"][key] = {"$ne" => value}
+
+      self
+    end
+
+    # Sort results in ascending order for the given key
+    # @param [String] key The key by which to sort
+    # @return [Query] self
+    def ascending(key)
+      @params["asc"] = key
+
+      self
+    end
+
+    # Sort results in descending order for the given key
+    # @param [String] key The key by which to sort
+    # @return [Query] self
+    def descending(key)
+      @params["desc"] = key
+
+      self
+    end
+
+    # To check that the value for a key is contained in a given array
+    # @param [String] key The key to check
+    # @param [Array] array An array of values
+    # @return [Query] self
+    def contained_in(key, array)
+      @params["query"][key] = {"$in" => array}
+
+      self
+    end
+
+    # To check that the value for a key is NOT contained in a given array
+    # @param [String] key The key to check
+    # @param [Array] array An array of values
+    # @return [Query] self
+    def not_contained_in(key, array)
+      @params["query"][key] = {"$nin" => array}
+
+      self
+    end
+
+    # To check that the given key exists
+    # @param [String] key
+    # @return [Query] self
+    def exists(key)
+      @params["query"][key] = {"$exists" => true}
+
+      self
+    end
+
+    # To check that the given key does not exist
+    # @param [String] key
+    # @return [Query] self
+    def not_exists(key)
+      @params["query"][key] = {"$exists" => false}
+
+      self
+    end
+
+    # Reference query a field
+    # @param [String] key
+    # @param [Query] query
+    def in_query(key, query)
+      @params["query"][key] = {"$in_query" => query.params["query"]}
+
+      self
+    end
+
+    # Reference query a field negatively
+    # @param [String] key
+    # @param [Query] query
+    def not_in_query(key, query)
+      @params["query"][key] = {"$nin_query" => query.params["query"]}
+
+      self
+    end
+
+    # Limit the number of results to a given number
+    # @param [Number] number
+    # @return [Query] self
+    def limit(number)
+      @params["limit"] = number
+
+      self
+    end
+
+    # Skip a give number of results
+    # @param [Number] number
+    # @return [Query] self
+    def skip(number)
+      @params["skip"] = number
+
+      self
+    end
+
+    # Return the count of objects instead of the result of the query
+    # @return [Query] self
+    def count
+      @params["count"] = true
+
+      self
+    end
+
+    # Include the count of objects matching the query in the result
+    # @return [Query] self
+    def include_count
+      @params["include_count"] = true
+
+      self
+    end
+
+    # Include reference fields in the response (joins)
+    # @param [String] key The reference field to include
+    # @return [Query] self
+    def include(key)
+      @params["include"] ||= []
+      @params["include"] << key
+
+      self
+    end
+
+    # Include the owner of the object in the parameter _owner
+    # @return [Query] self
+    def include_owner
+      @params["include_owner"] = true
+
+      self
+    end
+
+    # Include draft objects that haven't been published yet
+    # @return [Query] self
+    def include_drafts
+      @params["include_unpublished"] = true
+
+      self
+    end
+
+    # Include the schema of the class in the result
+    # @return [Query] self
+    def include_schema
+      @params["include_schema"] = true
+
+      self
+    end
+
+    # Execute the query
+    # @return [QueryResponse] response A hash containing the response
+    def exec
+      if !@class_uid
+        raise BuiltError, I18n.t("querying.class_uid")
+      end
+
+      uri = Built::Object.uri(@class_uid)
+
+      QueryResponse.new(
+        Built.client.request(uri, :get, nil, @params).parsed_response,
+        @class_uid
+      )
+    end
+  end
+
+  class QueryResponse
+    # Get objects in the response
+    # @return [Array] objects
+    def objects
+      @objects
+    end
+
+    # Get the count of objects
+    # @return [Number] count
+    def count
+      @count
+    end
+
+    # Get the included schema
+    # @return [Hash] schema
+    def schema
+      @schema
+    end
+
+    private
+
+    def initialize(response, class_uid)
+      @response   = response
+
+      if response["objects"].is_a?(Array)
+        @objects  = response["objects"].map {|o| Built::Object.new(class_uid, o)}
+      else
+        @objects  = []
+        @count    = response["objects"]
+      end
+
+      if response["count"]
+        @count    = response["count"]
+      end
+
+      if response["schema"]
+        @schema   = response["schema"]
+      end
+    end
+  end
+end

data/lib/built/timestamps.rb

@@ -0,0 +1,15 @@
+module Built
+  module Timestamps
+    def created_at
+      DateTime.parse self["created_at"]
+    end
+
+    def updated_at
+      DateTime.parse self["updated_at"]
+    end
+
+    def deleted_at
+      DateTime.parse self["deleted_at"]
+    end
+  end
+end

data/lib/built/util.rb

@@ -0,0 +1,7 @@
+module Built
+  class Util
+    def self.blank?(value)
+      value.respond_to?(:empty?) ? value.empty? : !value
+    end
+  end
+end

data/lib/locales/en.yml

@@ -0,0 +1,9 @@
+en:
+  waddap: "Welcome to built.io!"
+  required_parameter: "%{param} is a required parameter"
+  not_initialized: "Library is not initialized"
+  objects:
+    class_uid: "class_uid needs to be provided when initializing an object"
+    uid_not_set: "uid for this object needs to be set before attempting to fetch it"
+  querying:
+    class_uid: "class_uid needs to be provided to query for objects"

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: built.io
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- Suvish Thoovamalayil
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: httmultiparty
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! "    built.io is a Backend-as-a-Service (BaaS).\n\n    This is a Ruby
+  SDK that provides a convenient API.\n"
+email: vishy1618@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/built/constants.rb
+- lib/built/util.rb
+- lib/built/error.rb
+- lib/built/timestamps.rb
+- lib/built/application.rb
+- lib/built/i18n.rb
+- lib/built/client.rb
+- lib/built/class.rb
+- lib/built/query.rb
+- lib/built/object.rb
+- lib/locales/en.yml
+- lib/built.rb
+- MIT-LICENSE
+- README.md
+homepage: https://github.com/vishy1618/built.io-ruby-sdk
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: The built.io Ruby SDK
+test_files: []
+has_rdoc: