airtable 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 44001bc278b32cb324d355c6e89ef3ef0daee53b
+  data.tar.gz: f35bd0c0a6ce9b427684625d5e314913677b9e19
+SHA512:
+  metadata.gz: f530c2ede4381894784a64eb3a4a13e6e7d77ffe632388939d84baea2bc361fe53393888e868781a7aec564e5361b664fa8466aefc3249309019451e079c6521
+  data.tar.gz: 1466e6989283a7475819b94b34bd819fb9e2e8345fdded5538abee6f011a48897c815294e39a142617a4ba06eec72f8296d671cda69c306a670fa41e53377089

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in airtable.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Nathan Esquenazi
+
+MIT License
+
+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,122 @@
+# Airtable Ruby Client
+
+Easily connect to [airtable](https://airtable.com) data using ruby with access to all of the airtable features.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'airtable'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install airtable
+
+## Usage
+
+### Creating a Client
+
+First, be sure to register for an [airtable](https://airtable.com) account, create a data worksheet and [get an api key](https://airtable.com/account). Now, setup your Airtable client:
+
+```ruby
+# Pass in api key to client
+@client = Airtable::Client.new("keyPCx5W")
+```
+
+Your API key carries the same privileges as your user account, so be sure to keep it secret!
+
+### Accessing a Table
+
+Now we can access any table in our Airsheet account by referencing the [API docs](https://airtable.com/api):
+
+```ruby
+# Pass in the app key and table name
+@table = @client.table("appPo84QuCy2BPgLk", "Table Name")
+```
+
+### Querying Records
+
+Once you have access to a table from above, we can query a set of records in the table with:
+
+```ruby
+@records = @table.records
+```
+
+We can specify a `sort` order, `limit`, and `offset` as part of our query:
+
+```ruby
+@records = @table.records(:sort => ["Name", :asc], :limit => 50)
+@records # => [#<Airtable::Record :name=>"Bill Lowry", :email=>"billery@gmail.com">, ...]
+@records.offset #=> "itrEN2TCbrcSN2BMs"
+```
+
+This will return the records based on the query as well as an `offset` for the next round of records. We can then access the contents of any record:
+
+```ruby
+@bill = @record.first
+# => #<Airtable::Record :name=>"Bill Lowry", :email=>"billery@gmail.com", :id=>"rec02sKGVIzU65eV1">
+@bill[:id] # => "rec02sKGVIzU65eV2"
+@bill[:name] # => "Bill Lowry"
+@bill[:email] # => "billery@gmail.com"
+```
+
+Note that you can only request a maximimum of 100 records in a single query. To retrieve more records, use the "batch" feature below.
+
+### Batch Querying All Records
+
+We can also query all records in the table through a series of batch requests with:
+
+```ruby
+@records = @table.all(:sort => ["Name", :asc])
+```
+
+This executes a variable number of network requests (100 records per batch) to retrieve all records in a sheet. 
+
+### Finding a Record
+
+Records can be queried by `id` using the `find` method on a table:
+
+```ruby
+@record = @table.find("rec02sKGVIzU65eV2")
+# => #<Airtable::Record :name=>"Bill Lowry", :email=>"billery@gmail.com", :id=>"rec02sKGVIzU65eV1">
+```
+
+### Inserting Records
+
+Records can be inserted using the `create` method on a table:
+
+```ruby
+@record = Airtable::Record.new(:name => "Sarah Jaine", :email => "sarah@jaine.com")
+@table.create(record)
+# => #<Airtable::Record :name=>"Sarah Jaine", :email=>"sarah@jaine.com", :id=>"rec03sKOVIzU65eV4">
+```
+
+### Updating Records
+
+Records can be updated using the `update` method on a table:
+
+```ruby
+@record[:email] = "sarahjaine@updated.com"
+@table.update(record)
+# => #<Airtable::Record :name=>"Sarah Jaine", :email=>"sarahjaine@updated.com", :id=>"rec03sKOVIzU65eV4">
+```
+
+### Deleting Records
+
+Records can be updated using the `update` method on a table:
+
+```ruby
+@table.destroy(record)
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/nesquena/airtable-ruby/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = "test/*_test.rb"
+end

data/airtable.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'airtable/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "airtable"
+  spec.version       = Airtable::VERSION
+  spec.authors       = ["Nathan Esquenazi"]
+  spec.email         = ["nesquena@gmail.com"]
+  spec.summary       = %q{Easily connect to airtable data using ruby}
+  spec.description   = %q{Easily connect to airtable data using ruby with access to all of the airtable features.}
+  spec.homepage      = "https://github.com/nesquena/airtable-ruby"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "httparty"
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "minitest", "~> 5.6.0"
+  spec.add_development_dependency "fakeweb", "~> 1.3"
+end

data/lib/airtable.rb

@@ -0,0 +1,12 @@
+require 'httparty'
+require 'delegate'
+require "airtable/version"
+require 'airtable/resource'
+require 'airtable/record'
+require 'airtable/record_set'
+require 'airtable/table'
+require 'airtable/client'
+
+module Airtable
+  # Nothing for now
+end

data/lib/airtable/client.rb

@@ -0,0 +1,20 @@
+# Allows access to data on airtable
+#
+# Fetch all records from table:
+#
+# client = Airtable::Client.new("keyPtVG4L4sVudsCx5W")
+# client.table("appXXV84QuCy2BPgLk", "Sheet Name").all
+#
+
+module Airtable
+  class Client
+    def initialize(api_key)
+      @api_key = api_key
+    end
+
+    # table("appXXV84QuCy2BPgLk", "Sheet Name")
+    def table(app_token, worksheet_name)
+      Table.new(@api_key, app_token, worksheet_name)
+    end
+  end # Client
+end # Airtable

data/lib/airtable/record.rb

@@ -0,0 +1,67 @@
+module Airtable
+
+  class Record
+    def initialize(attrs={})
+      @columns_map = attrs.keys
+      @attrs = HashWithIndifferentAccess.new(Hash[attrs.map { |k, v| [ to_key(k), v ] }])
+      @attrs.map { |k, v| define_accessor(k) }
+    end
+
+    def id; @attrs["id"]; end
+    def id=(val); @attrs["id"] = val; end
+
+    # Return given attribute based on name or blank otherwise
+    def [](name)
+      @attrs.has_key?(to_key(name)) ? @attrs[to_key(name)] : ""
+    end
+
+    # Set the given attribute to value
+    def []=(name, value)
+      @attrs[to_key(name)] = value
+      define_accessor(name) unless respond_to?(name)
+    end
+
+    def inspect
+      "#<Airtable::Record #{attributes.map { |a, v| ":#{a}=>#{v.inspect}" }.join(", ")}>"
+    end
+
+    # Hash of attributes with underscored column names
+    def attributes; @attrs; end
+
+    # Hash with keys based on airtable original column names
+    def fields; Hash[@columns_map.map { |k| [ k, @attrs[to_key(k)] ] }]; end
+
+
+    def method_missing(name, *args, &blk)
+      # Accessor for attributes
+      if args.empty? && blk.nil? && @attrs.has_key?(name)
+        @attrs[name]
+      else
+        super
+      end
+    end
+
+    def respond_to?(method_name, include_private = false)
+      @attrs.has_key?(name) || super
+    end
+
+    protected
+
+    def to_key(string)
+      string.is_a?(Symbol) ? string : underscore(string).to_sym
+    end
+
+    def underscore(string)
+      string.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        gsub(/\s/, '_').tr("-", "_").downcase
+    end
+
+    def define_accessor(name)
+      self.class.send(:define_method, name) { @attrs[name] }
+    end
+
+  end # Record
+
+end # Airtable

data/lib/airtable/record_set.rb

@@ -0,0 +1,22 @@
+module Airtable
+
+  # Contains records and the offset after a record query
+  class RecordSet < SimpleDelegator
+
+    attr_reader :records, :offset
+
+    # results = { "records" => [{ ... }], "offset" => "abc5643" }
+    # response from records api
+    def initialize(results)
+      # Parse records
+      @records = results && results["records"] ?
+        results["records"].map { |r| Record.new(r["fields"].merge("id" => r["id"])) } : []
+      # Store offset
+      @offset = results["offset"]
+      # Assign delegation object
+      __setobj__(@records)
+    end
+
+  end # Record
+
+end # Airtable

data/lib/airtable/resource.rb

@@ -0,0 +1,17 @@
+module Airtable
+  # Base class for authorized resources sending network requests
+  class Resource
+    include HTTParty
+    base_uri 'https://api.airtable.com/v0/'
+    # debug_output $stdout
+
+    attr_reader :api_key, :app_token, :worksheet_name
+
+    def initialize(api_key, app_token, worksheet_name)
+      @api_key = api_key
+      @app_token = app_token
+      @worksheet_name = worksheet_name
+      self.class.headers({'Authorization' => "Bearer #{@api_key}"})
+    end
+  end # AuthorizedResource
+end # Airtable

data/lib/airtable/table.rb

@@ -0,0 +1,73 @@
+module Airtable
+
+  class Table < Resource
+    # Maximum results per request
+    LIMIT_MAX = 100
+
+    # Fetch all records iterating through offsets until retrieving the entire collection
+    # all(:sort => ["Name", :desc])
+    def all(options={})
+      offset = nil
+      results = []
+      begin
+        options.merge!(:limit => LIMIT_MAX, :offset => offset)
+        response = records(options)
+        results += response.records
+        offset = response.offset
+      end until offset.nil? || offset.empty? || results.empty?
+      results
+    end
+
+    # Fetch records from the sheet given the list options
+    # Options: limit = 100, offset = "as345g", sort = ["Name", "asc"]
+    # records(:sort => ["Name", :desc], :limit => 50, :offset => "as345g")
+    def records(options={})
+      options["sortField"], options["sortDirection"] = options.delete(:sort) if options[:sort]
+      results = self.class.get(worksheet_url, query: options).parsed_response
+      RecordSet.new(results)
+    end
+
+    # Returns record based given row id
+    def find(id)
+      result = self.class.get(worksheet_url + "/" + id).parsed_response
+      Record.new(result["fields"].merge("id" => result["id"])) if result.present? && result["id"]
+    end
+
+    # Creates a record by posting to airtable
+    def create(record)
+      result = self.class.post(worksheet_url,
+        :body => { "fields" => record.fields }.to_json,
+        :headers => { "Content-type" => "application/json" }).parsed_response
+      if result.present? && result["id"].present?
+        record.id = result["id"]
+        record
+      else # failed
+        false
+      end
+    end
+
+    # Replaces record in airtable based on id
+    def update(record)
+      result = self.class.put(worksheet_url + "/" + id,
+        :body => { "fields" => record.fields }.to_json,
+        :headers => { "Content-type" => "application/json" }).parsed_response
+      if result.present? && result["id"].present?
+        record
+      else # failed
+        false
+      end
+    end
+
+    # Deletes record in table based on id
+    def destroy(id)
+      self.class.delete(worksheet_url + "/" + id).parsed_response
+    end
+
+    protected
+
+    def worksheet_url
+      "/#{app_token}/#{URI.encode(worksheet_name)}"
+    end
+  end # Table
+
+end # Airtable

data/lib/airtable/version.rb

@@ -0,0 +1,3 @@
+module Airtable
+  VERSION = "0.0.2"
+end

data/test/airtable_test.rb

@@ -0,0 +1,25 @@
+require 'test_helper'
+
+describe Airtable do
+  before do
+    @client_key = "12345"
+    @app_key = "appXXV84Qu"
+    @sheet_name = "Test"
+  end
+
+  describe "with Airtable" do
+    it "should allow client to be created" do
+      @client = Airtable::Client.new(@client_key)
+      assert_kind_of Airtable::Client, @client
+      @table = @client.table(@app_key, @sheet_name)
+      assert_kind_of Airtable::Table, @table
+    end
+
+    it "should fetch record set" do
+      stub_airtable_response("https://api.airtable.com/v0/#{@app_key}/#{@sheet_name}", { "records" => [], "offset" => "abcde" })
+      @table = Airtable::Client.new(@client_key).table(@app_key, @sheet_name)
+      @records = @table.records
+      assert_equal "abcde", @records.offset
+    end
+  end # describe Airtable
+end # Airtable

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+require 'airtable'
+require 'fakeweb'
+require 'minitest/pride'
+require 'minitest/autorun'
+
+FakeWeb.allow_net_connect = false
+
+def stub_airtable_response(url, response)
+  FakeWeb.register_uri(:get, url, :body => response.to_json, :content_type => "application/json")
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: airtable
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Nathan Esquenazi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 5.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 5.6.0
+- !ruby/object:Gem::Dependency
+  name: fakeweb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: Easily connect to airtable data using ruby with access to all of the
+  airtable features.
+email:
+- nesquena@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- airtable.gemspec
+- lib/airtable.rb
+- lib/airtable/client.rb
+- lib/airtable/record.rb
+- lib/airtable/record_set.rb
+- lib/airtable/resource.rb
+- lib/airtable/table.rb
+- lib/airtable/version.rb
+- test/airtable_test.rb
+- test/test_helper.rb
+homepage: https://github.com/nesquena/airtable-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.0.6
+signing_key: 
+specification_version: 4
+summary: Easily connect to airtable data using ruby
+test_files:
+- test/airtable_test.rb
+- test/test_helper.rb