airtable2 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93c86827ca58e71692144e71bb18ae5ab0db94fb0c1686982357e62516bee07f
-  data.tar.gz: e4300c97ab34a37fc370ff796761d436afca0e7cd2a4d629c7debef61a490d71
+  metadata.gz: 289287db343e46821fa736305ee64eb1a9fc08a58c662b3877cf10643ea63737
+  data.tar.gz: b25cca2262cc2d91ff241fbd479c58efcebdc77cb95dbe9a869f19d990593e11
 SHA512:
-  metadata.gz: 13a8c56ad23fe5caedb41d782baf7c39b860d6bb8f157c2d3756a71ed1bf8fcd198fe84df70038d21b4e913702a989b2981394c66b2a26a6dd7ad8f50a1a6636
-  data.tar.gz: cdf035a603f61131726559639541b5f11cfe706625533d01c2dd7c6cc523a850442fd832e4e79027e0f6e2fb405cea2f5d4c476124f024410eccd4443a52d618
+  metadata.gz: 97493ce00abb1c1306f7c8d5efc0b0b0c21b9155a8f64458138e11e61b5fc9f504241137391f3bd4184fab4434d8bc0e11401407034a1ae5561b85cd64393fb5
+  data.tar.gz: 38f2292dc125c1f3cffb1c6a35f48ea79824029b1bd9d1b0824c09bbc8705a8b8c3791962f9bce4a9e7bd1105d3290b9b05740661cc82297815331cac028acfc

data/README.md

@@ -27,21 +27,38 @@ First, be sure to register for an [airtable](https://airtable.com) account,  set
 @client = Airtable::Client.new('your.token.goes.here')
 ```
 
-### Accessing Data
+### Simple Usage
+
+#### Reading
 
 Now we can access our base
 
 ```ruby
+# Retrieve with a specific ID
 @base = @client.base('appExAmPlE')
+# or
+@base = @client.bases.first
 ```
 
 and its tables
 
 ```ruby
-@tables = @base.tables
+# Retrieve with a specific ID
+@table = @base.table('tblExAmPle')
+# or
+@table = @base.tables.first
+```
+
+and a table's records,
+
+```ruby
+# Retrieve with a specific ID
+@record = @table.record('recExAmPle')
+# or
+@record = @table.records.first
 ```
 
-and a table's records, so you can navigate the belongs_to/has_many relationships the way God intended:
+so you can navigate the belongs_to/has_many relationships the way God intended:
 
 ```ruby
 @record = @client.bases.first.tables.first.records.first
@@ -50,9 +67,15 @@ and a table's records, so you can navigate the belongs_to/has_many relationships
 
 Note that objects' child records are memoized to avoid unnecessary API calls. If sensitive to stale data, be sure to use the objects instantiated most recently.
 
-### Manipulating Tables
+To get the fields of a table, its simply
+
+```ruby
+@fields = @table.fields
+```
+
+#### Writing
 
-Create a new table with:
+Create a table in a base like so
 
 ```ruby
 @table = @base.create_table({ name: 'Names', description: 'A list of names', fields: [{ name: 'name', type: 'singleLineText' }] })
@@ -64,32 +87,38 @@ You can update at a table's metadata with the `update` method:
 @table.update({ description: 'Updated description' })
 ```
 
-### Querying Records
-
-Once you have access to a table from above, we can query a set of records in the table with:
+You can add a column to a table...
 
 ```ruby
-@records = @table.records
+@field = @table.add_field({'description': 'Whether I have visited this apartment yet.', 'name': 'Visited', 'type': 'checkbox', 'options': { 'color': 'greenBright', 'icon': 'check'} })
 ```
 
-### Inserting Records
+...and update it
+
+```ruby
+@field = @field.update({'description': 'Whether I have rented this apartment yet.', 'name': 'Rented'})
+```
 
 A single record or an array of records can be inserted using the `create_records` method on a table (max 10 at a time):
 
 ```ruby
+# Single
 @table.create_records({ 'Name': 'name value', 'Age': 35 })
+# Array
+@table.create_records([{ 'Name': 'name value', 'Age': 35 }, { 'Name': 'another name value', 'Age': 40 }])
 ```
 
-### Deleting Records
-
-A single record or an array of records can be destroyed by passing their ids to the `delete_records` method on a table:
+A single record or an array of records can be destroyed by passing their ids to the `delete_records` method on a table (max 10 at a time):
 
 ```ruby
-@record = @table.records[0]
-@table.delete_records(@record.id)
+@records = @table.records
+# Single
+@table.delete_records(@records.first.id)
+# Array
+@table.delete_records(@records.map(&:ids))
 ```
 
-Or as a convenience, you can delete all records with the `dump` method
+Or as a convenience, you can delete all records with the `dump` method, which will abide by the API's rate limiting.
 
 ```ruby
 @table.dump

data/lib/airtable/base.rb

@@ -28,7 +28,7 @@ class Airtable::Base < Airtable::Resource
 
       check_and_raise_error(response)
 
-      response['tables'].map { Airtable::Table.new(@token, @id, _1['id'], _1) }
+      response['tables'].map { Airtable::Table.new(@token, self, _1['id'], _1) }
     end
   end
 

data/lib/airtable/field.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Object corresponding to an Airtable Field
+class Airtable::Field < Airtable::Resource
+  attr_reader :base, :table, :name, :type, :options
+
+  def initialize(token, table, id, data = nil)
+    super(token)
+    @table = table
+    @base = @table.base
+    @id = id
+    data&.each_key do |key|
+      instance_variable_set(:"@#{key}", data[key])
+    end
+  end
+
+  # @return [Airtable::Field]
+  # @see https://airtable.com/developers/web/api/update-field
+  def update(field_data)
+    response = self.class.patch(field_url,
+                                body: field_data.to_json).parsed_response
+
+    check_and_raise_error(response)
+
+    Airtable::Field.new(@token, @table, response)
+  end
+
+  protected
+
+  # Endpoint for tables
+  def field_url = "/v0/meta/bases/#{@base.id}/tables/#{@table.id}/fields/#{@id}"
+end

data/lib/airtable/record.rb

@@ -2,10 +2,12 @@
 
 # Object corresponding to an Airtable Record
 class Airtable::Record < Airtable::Resource
-  def initialize(token, base_id, table_id, id, data = nil)
+  attr_reader :table, :base
+
+  def initialize(token, table, id, data = nil)
     super(token)
-    @base_id = base_id
-    @table_id = table_id
+    @table = table
+    @base = @table.base
     @id = id
     @data = data
   end
@@ -23,10 +25,6 @@ class Airtable::Record < Airtable::Resource
     end
   end
 
-  # Instantiate record's table
-  # @return [Airtable::Table]
-  def table = Airtable::Table.new(token, @base_id, @table_id)
-
   # @return [Airtable::Record]
   # @see https://airtable.com/developers/web/api/update-record
   def update(record_data)
@@ -35,11 +33,11 @@ class Airtable::Record < Airtable::Resource
 
     check_and_raise_error(response)
 
-    Airtable::Record.new @token, @base_id, @table_id, response['id'], response
+    Airtable::Record.new @token, @base.id, @table.id, response['id'], response
   end
 
   protected
 
   # Endpoint for records
-  def record_url = "/v0/#{@base_id}/#{@table_id}/#{@id}"
+  def record_url = "/v0/#{@base.id}/#{@table.id}/#{@id}"
 end

data/lib/airtable/table.rb

@@ -2,11 +2,11 @@
 
 # Object corresponding to an Airtable Table
 class Airtable::Table < Airtable::Resource
-  attr_reader :name
+  attr_reader :name, :base
 
-  def initialize(token, base_id, id, data = nil)
+  def initialize(token, base, id, data = nil)
     super(token)
-    @base_id = base_id
+    @base = base
     @id = id
     @data = data
   end
@@ -16,9 +16,16 @@ class Airtable::Table < Airtable::Resource
   # @see https://airtable.com/developers/web/api/get-base-schema
   def data = @data ||= base.tables.find { _1.id == @id }.data
 
-  # Instantiate table's base
-  # @return [Airtable::Base]
-  def base = Airtable::Base.new(token, @base_id)
+  # @return [Airtable::Field]
+  # @see https://airtable.com/developers/web/api/create-field
+  def create_field(field_data)
+    response = self.class.post("/v0/meta/bases/#{@base.id}/tables/#{@id}/fields",
+                               body: field_data.to_json).parsed_response
+
+    check_and_raise_error(response)
+
+    Airtable::Field.new(@token, self, response['id'], response)
+  end
 
   # @return [Array<Airtable::Record>]
   # @see https://airtable.com/developers/web/api/list-records
@@ -28,24 +35,27 @@ class Airtable::Table < Airtable::Resource
 
       check_and_raise_error(response)
 
-      response['records'].map { Airtable::Record.new(@token, @base_id, @id, _1['id'], _1) }
+      response['records'].map { Airtable::Record.new(@token, self, _1['id'], _1) }
     end
   end
 
+  # @return [Array<Airtable::Field>]
+  def fields = @fields ||= data['fields'].map { Airtable::Field.new(@token, self, _1['id'], _1) }
+
   # Instantiate record in table
   # @param record_id [String] ID of record
   # @return [Airtable::Record]
-  def record(record_id) = Airtable::Record.new(@token, @base_id, @id, record_id)
+  def record(record_id) = Airtable::Record.new(@token, @base.id, @id, record_id)
 
   # @return [Airtable::Table]
   # @see https://airtable.com/developers/web/api/update-table
   def update(table_data)
-    response = self.class.patch("/v0/meta/bases/#{@base_id}/tables/#{@id}",
+    response = self.class.patch("/v0/meta/bases/#{@base.id}/tables/#{@id}",
                                 body: table_data.to_json).parsed_response
 
     check_and_raise_error(response)
 
-    Airtable::Table.new @token, @base_id, response['id'], response
+    Airtable::Table.new @token, @base.id, response['id'], response
   end
 
   # @param [Array] Record objects to create
@@ -58,7 +68,7 @@ class Airtable::Table < Airtable::Resource
 
     check_and_raise_error(response)
 
-    response['records'].map { Airtable::Record.new(@token, @base_id, @id, _1['id'], _1) }
+    response['records'].map { Airtable::Record.new(@token, @base.id, @id, _1['id'], _1) }
   end
 
   # @param [Array] IDs of records to delete
@@ -75,15 +85,18 @@ class Airtable::Table < Airtable::Resource
   end
 
   # Deletes all table's records
+  # @return [Integer] Number of deleted records
   def dump
-    records.map(&:id).each_slice(10) do |record_id_set|
+    ids = records.map(&:id)
+    ids.each_slice(10) do |record_id_set|
       delete_records(record_id_set)
       sleep(0.2)
     end
+    ids.size
   end
 
   protected
 
   # Endpoint for tables
-  def table_url = "/v0/#{@base_id}/#{@id}"
+  def table_url = "/v0/#{@base.id}/#{@id}"
 end

data/lib/airtable/version.rb

@@ -2,5 +2,5 @@
 
 # Version
 module Airtable
-  VERSION = '0.2.4'
+  VERSION = '0.2.5'
 end

data/lib/airtable.rb

@@ -5,6 +5,7 @@ require 'json'
 
 require 'airtable/version'
 require 'airtable/resource'
+require 'airtable/field'
 require 'airtable/record'
 require 'airtable/table'
 require 'airtable/base'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: airtable2
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - Andrew Seroff
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-28 00:00:00.000000000 Z
+date: 2024-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -171,6 +171,7 @@ files:
 - lib/airtable/base.rb
 - lib/airtable/client.rb
 - lib/airtable/error.rb
+- lib/airtable/field.rb
 - lib/airtable/record.rb
 - lib/airtable/resource.rb
 - lib/airtable/table.rb