airbased 0.0.1.pre.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81a62f187752dc1b866554329511e2f03904917caa67e85e16b6a03bc0a063fa
+  data.tar.gz: a7ed8eb8455da778e511aea3385fe603700b2aa837f3a57766594f01156013af
+SHA512:
+  metadata.gz: a053f69c8b323542f072155b8e537d61fe1f52ff027310a9706671e28202b7e8559d847de7a35d3bd0fe70bf2d11bb35a17fa27d6b467a3df5db072fc43f0910
+  data.tar.gz: b4fbf93726016e55e80c932cb34d9c0a7db9644e811ad3b9ad4b93008f8689e09aaf216c5dba9d1bb8d01ef91fba7a6d9b70438fe2149e1ee4f659c303073653

data/.rubocop.yml

@@ -0,0 +1,15 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
+  NewCops: enable
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1 @@
+## [Unreleased]

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at 43987794+alokhmutov@users.noreply.github.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Aleks Lokhmutov
+
+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,60 @@
+# Airbased
+
+Ruby interface to the Airtable’s API.
+
+## Note
+
+The library is in early development, so breaking changes are possible. It implements all records API methods (including
+batch operations), except Sync CSV data and attachment upload.
+
+Feedback and contributions are most welcome!
+
+## Start using Airbased
+
+# Install the gem.
+
+`gem install airbased --pre`
+
+Or in a Gemfile:
+
+`gem 'airbased', '0.0.1-alpha'`
+
+# Define an API key, then define a base.
+
+```ruby
+Airbased.api_key = "patxxx"
+
+# define a new base
+MyBase = Airbased::Base.new("appxxxxxxxxxxxxxx")
+
+# define a table from the base's schema
+MyTable = MyBase["Table 1"] # you can use table name or id
+
+# ... or though an ad-hoc definition
+MyTable = Airbased.table(Airbased.api_key, "appxxxxxxxxxxxxxx", "tblxxxxxxxxxxxxxx")
+
+# create a record
+new_record = MyTable.create({"Name" => "a new name"})
+
+# ... or many records at once, Airbased will take care of batching!
+fields = [{ "Name" => "a new name 2" }, {"Name" => "a new name 3"}]
+records = MyTable.create(fields)
+
+# delete a record
+new_record.delete
+
+# fetch records
+records = MyTable.all
+
+# update records
+record = records[0]
+record["Name"] = "newer name"
+record.save
+
+# upsert records
+records = MyTable.upsert(fields, merge_on: ["Name"])
+
+# if something goes wrong...
+Airbased.debug = true
+# will write requests info into stdout
+```

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: %i[test]

data/airbased.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/airbased/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "airbased"
+  spec.version = Airbased::VERSION
+  spec.authors = ["Aleks Lokhmutov"]
+  spec.email = ["43987794+alokhmutov@users.noreply.github.com"]
+
+  spec.summary = "Ruby interface to the Airtable’s API."
+  spec.homepage = "https://github.com/alokhmutov/airbased"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/alokhmutov/airbased"
+  spec.metadata["changelog_uri"] = "https://github.com/alokhmutov/airbased/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+
+  spec.require_paths = ["lib"]
+
+  # Dependencies
+  spec.add_dependency "httparty"
+
+end

data/lib/airbased/airtable/airtable.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "httparty"
+
+module Airbased
+  # The Airtable class is an HTTParty client for Airtable API.
+  # It handles headers (incl. authorization), rate limits, error handling,
+  # and basic request/response parsing.
+  class Airtable
+    include HTTParty
+    include Errors
+    base_uri 'https://api.airtable.com/v0/'
+    headers 'User-Agent' => "Airbased Ruby Gem/#{Airbased::VERSION}",
+            'Content-Type' => 'application/json'
+
+    class << self
+      attr_accessor :requests
+
+      def with_rate_limit
+        # Keep only the timestamps within the last second
+        @requests.reject! { |timestamp| Time.now - timestamp > 1 }
+
+        if @requests.size >= 5
+          sleep_time = 1 - (Time.now - @requests.first)
+          sleep(sleep_time) if sleep_time.positive?
+        end
+
+        response = yield
+
+        request_time =
+          begin
+            Time.parse(response.headers["date"])
+          rescue
+            Time.now
+          end
+
+        @requests << request_time
+
+        response
+      end
+
+      # sets an authorization header with a custom, if passed, or general api key
+      def authorization(options)
+        api_key = (options.dig(:api_key) && options.delete(:api_key)) || Airbased.api_key
+        options[:headers] ||= { Authorization: "Bearer #{api_key}" }
+      end
+
+      # formating request body to json
+      def process_data(data)
+        processed_data = data.compact
+        processed_data = deep_transform_keys(processed_data) { |key| from_snake(key) }
+
+        JSON.dump(processed_data)
+      end
+
+      # formating response body to be accessible with conventional snake-case symbols
+      def process_result(result)
+        deep_transform_keys(result) { |key| to_snake(key) }
+      end
+
+      # recursively transforms keys of a payload, except for field names
+      def deep_transform_keys(obj, &block)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), result|
+            new_key = yield(key.to_s).to_sym
+            result[new_key] = if key.to_s == "fields"
+                                value
+                              else
+                                deep_transform_keys(value, &block)
+                              end
+          end
+        when Array
+          obj.map { |e| deep_transform_keys(e, &block) }
+        else
+          obj
+        end
+      end
+
+      def to_snake(str)
+        str.gsub(/([A-Z])/, '_\1').downcase
+      end
+
+      def from_snake(str)
+        str.gsub(/_(.)/) { Regexp.last_match(1).upcase }
+      end
+    end
+
+    @requests = []
+
+    # processing a custom api key and debug options, formatting data, then making request
+    [:get, :post, :patch, :put, :delete].each do |method|
+      define_singleton_method(method) do |path, data = nil, options = {}, &block|
+        # setting API key in request
+        authorization(options)
+
+        # formatting data to json
+        options[:body] = process_data(data) if data
+
+        # would output request info if enabled
+        options[:debug_output] = $stdout if Airbased.debug
+
+        response = with_error_handling do
+          with_rate_limit do # processes rate limits
+            super(path, options, &block) # then delegates to the HTTParty method
+          end
+        end
+        process_result(response.parsed_response)
+      end
+    end
+  end
+end

data/lib/airbased/airtable/errors.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Airbased
+  class Airtable
+    module Errors
+      class AirtableError < StandardError; end
+
+      class BadRequest < AirtableError; end
+      class Unauthorized < AirtableError; end
+      class Forbidden < AirtableError; end
+      class NotFound < AirtableError; end
+      class PayloadTooLarge < AirtableError; end
+      class InvalidRequest < AirtableError; end
+      class TooManyRequests < AirtableError; end
+      class InternalServerError < AirtableError; end
+      class BadGateway < AirtableError; end
+      class ServiceUnavailable < AirtableError; end
+
+      def Airtable.with_error_handling
+        response = yield
+
+        case response.code
+        when 200
+          response
+        when 400
+          raise BadRequest, response["error"]["message"]
+        when 401
+          raise Unauthorized, response["error"]["message"]
+        when 403
+          raise Forbidden, response["error"]["message"]
+        when 404
+          raise NotFound, response["error"]["message"]
+        when 413
+          raise PayloadTooLarge, response["error"]["message"]
+        when 422
+          raise InvalidRequest, response["error"]["message"]
+        when 429
+          raise TooManyRequests, response["error"]["message"]
+        when 500
+          raise InternalServerError, response["error"]["message"]
+        when 502
+          raise BadGateway, response["error"]["message"]
+        when 503
+          raise ServiceUnavailable, response["error"]["message"]
+        end
+      rescue Net
+        puts "retrying"
+        retry
+      rescue BadGateway
+        puts "retrying bad gateway"
+        retry
+      end
+    end
+  end
+end

data/lib/airbased/base.rb

@@ -0,0 +1,51 @@
+module Airbased
+  # The `Airbased::Base` class represents an Airtable base and
+  # provides methods to interact with the base.
+  #
+  # @attr_accessor [String] :base_id the unique identifier for the base
+  # @attr_accessor [Array<Table>] :tables the tables associated with the base
+  # @attr_accessor [String] :api_key the API key used for authentication
+  class Base
+    attr_accessor :base_id, :tables, :api_key
+
+    # Initializes a new instance of the Base class.
+    #
+    # @param base_id [String] the unique identifier for the base
+    # @param api_key [String, nil] the API key used for authentication (optional)
+    def initialize(base_id, api_key: nil)
+      @base_id = base_id
+      @api_key = api_key || Airbased.api_key
+    end
+
+    # Fetches the schema of the Airtable base and updates the @tables variable.
+    #
+    # @return [Array<Airbased::Table>] the tables associated with the base
+    def schema
+      response = Airtable.get("/meta/bases/#{@base_id}/tables")
+      @tables = response[:tables].map { |table| Airbased::Table.new(**table, base_id: @base_id) }
+    end
+
+    # Retrieves a table from the base by its id or name. Makes an API request to fetch the schema if tables have not been loaded yet.
+    #
+    # @param table_key [String] the key of the table to retrieve. This can be either the table's ID or name.
+    # @return [Airbased::Table, nil] the table with the specified key, or nil if no such table exists.
+    def [](table_key)
+      schema if @tables.nil?
+      table = @tables.find { |table| table.id == table_key || table.name == table_key }
+      raise Airbased::Error.new("Table with '#{table_key}' not found in schema") if table.nil?
+
+      table
+    end
+
+    # Creates a new table in the Airtable base.
+    #
+    # @param name [String] the name of the new table
+    # @param fields [Array<Hash>] the fields of the new table
+    # @param description [String, nil] an optional description for the new table
+    # @return [Airbased::Table] the newly created table
+    def create_table(name:, fields:, description: nil)
+      response = Airbased::Airtable.post("/meta/bases/#{@base_id}/tables", { name:, fields:, description: })
+      Table.new(**response, base_id: @base_id)
+    end
+  end
+end

data/lib/airbased/record/persistence.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Airbased
+  class Record
+    # API methods for Airtable records.
+    module Persistence
+      # Deletes a record from an Airtable table.
+      #
+      # @return a frozen [Record] of the deleted record
+      def delete
+        Airtable.delete("/#{@table.base_id}/#{@table.table_key}/#{@id}", nil, table.options)
+        @destroyed = true
+        freeze
+        self
+      end
+
+      # Updates the fields of a record in an Airtable table.
+      #
+      # @param fields [Hash] The fields to update.
+      # @param overwrite [Boolean] Whether to overwrite the existing fields (default: false).
+      # @param typecast [Boolean] Whether to enable typecasting for the fields (default: false).
+      # @return [Record] The updated record.
+      def update(fields, overwrite: false, typecast: false)
+        response = if overwrite
+                     Airtable.put("/#{@table.base_id}/#{@table.table_key}/#{@id}", { fields:, typecast: }, table.options)
+                   else
+                     Airtable.patch("/#{@table.base_id}/#{@table.table_key}/#{@id}", { fields:, typecast: }, table.options)
+                   end
+        self.fields = response[:fields]
+        self
+      end
+
+      # Saves the record to the Airtable table.
+      #
+      # @param typecast [Boolean] Whether to enable typecasting for the fields (default: false).
+      # @return [Record] Returns the saved record.
+      def save(typecast: false)
+        if new_record?
+          record = @table.create(@fields, typecast:)
+          self.fields = record.fields
+          @created_time = record.created_time
+          @id = record.id
+          self
+        else
+          update(@fields, typecast:)
+        end
+      end
+    end
+  end
+end

data/lib/airbased/record.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Airbased
+  # The Record class represents an individual record within an Airtable table.
+  class Record
+    include Record::Persistence
+    attr_reader :id, :fields, :created_time, :table, :destroyed
+
+    # Initializes a new Record instance.
+    #
+    # @param id [String] The ID of the record.
+    # @param fields [Hash] The fields of the record.
+    # @param created_time [String] The creation time of the record.
+    # @param table [Table] The table object to which the record belongs, expected to have `base_id` and `id` attributes.
+    def initialize(fields:, table:, id: nil, created_time: nil)
+      @id = id
+      @created_time = Time.parse(created_time) if created_time
+      self.fields = fields
+      @table = table
+    end
+
+    # Overwrites the fields of the record, transforming the keys to strings.
+    #
+    # @param fields [Hash] The fields to set, with keys that will be transformed to strings.
+    # @return [void]
+    def fields=(fields)
+      @fields = Hash.new { |hash, key| hash[key.to_s] if key.is_a?(Symbol) }
+      fields.each do |key, value|
+        @fields[key.to_s] = value
+      end
+    end
+
+    # Assigns new values to the record's fields, transforming the keys to strings.
+    #
+    # @param new_fields [Hash] The new values to assign to the record's fields.
+    # @return [void] Always returns nil.
+    def assign(new_fields)
+      @fields.update(new_fields.transform_keys(&:to_s))
+      nil
+    end
+
+    # Checks if the record is new (i.e., does not have an id).
+    #
+    # @return [Boolean] True if the record is new, false otherwise.
+    def new_record?
+      !id
+    end
+
+    # Checks if the record has been destroyed.
+    #
+    # @return [Boolean] True if the record is destroyed, false otherwise.
+    def destroyed?
+      !!destroyed
+    end
+
+    # Retrieves the value of the specified field.
+    #
+    # @param field [String, Symbol] The field name to retrieve the value for.
+    # @return [Object] The value of the specified field.
+    def [](field)
+      @fields[field]
+    end
+
+    # Sets the value of the specified field.
+    #
+    # @param key [String, Symbol] The field name to set the value for.
+    # @param value [Object] The value to set for the specified field.
+    # @return [void]
+    def []=(key, value)
+      @fields[key.to_s] = value
+    end
+
+    # Compares the current record with another object for equality.
+    #
+    # @param other [Object] The object to compare with.
+    # @return [Boolean] True if the other object is a Record and has the same id and fields, false otherwise.
+    def ==(other)
+      other.is_a?(Record) && id == other.id && fields == other.fields
+    end
+
+    # Converts the record to a hash representation.
+    #
+    # @return [Hash] A hash containing the record's id, fields, created_time, table key, and base id.
+    def to_h
+      {
+        id: @id,
+        fields: @fields,
+        created_time: @created_time,
+        table: @table.table_key,
+        base: @table.base_id
+      }
+    end
+
+    def to_api_hash
+      {
+        "id" => @id,
+        "fields" => @fields
+      }.compact
+    end
+
+    # Generates a link to the record in the Airtable table.
+    #
+    # @raise [Airbased::Error] If the table does not have an id (name only won't work in this case), or if a record does not have an id.
+    # @return [String] The URL link to the record.
+    def link
+      raise Airbased::Error.new("Record's table needs a table id to generate a link") unless @table.id
+      raise Airbased::Error.new("Record does not have an id to generate a link, it must be saved first") unless @id
+
+      "https://airtable.com/#{@table.base_id}/#{@table.id}/#{@id}"
+    end
+  end
+end

data/lib/airbased/table/persistence.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Airbased
+  class Table
+    # Persistence API methods for Airtable tables
+    module Persistence
+      include Airbased::Validation
+      # Creates new records in the Airtable base.
+      #
+      # The records parameter can either be a single hash or an array of hashes, where each hash represents a record.
+      #
+      # @param record_or_records [Hash, Array<Hash>] The records to be created. Must be a hash or an array of hashes.
+      # @param typecast [Boolean] (false) Whether to automatically typecast values. Defaults to false.
+      # @return [Record, Array<Record>] The created record(s). Returns a single record if one record is created, otherwise returns an array of records.
+      def create(record_or_records, typecast: false)
+        records = record_or_records.is_a?(Hash) ? [record_or_records.dup] : record_or_records.dup
+        records = hash_or_record_to_hash(records, id_required: false)
+
+        returned_records = records.each_slice(10).map do |slice|
+          create_slice(slice, typecast:)
+        end.flatten
+        returned_records.size == 1 ? returned_records.first : returned_records
+      end
+
+      # Updates existing records in the Airtable base.
+      #
+      # The records parameter can either be an array of Record objects or an array of hashes, where each hash represents a record.
+      #
+      # @param records [Array<Record, Hash>] The records to be updated. Must be an array of Record objects or hashes.
+      # @param overwrite [Boolean] (false) Whether to overwrite existing records. If true, will clear the fields not in the request. Defaults to false.
+      # @param typecast [Boolean] (false) Whether to automatically typecast values. Defaults to false.
+      # @return [Array<Record>] The updated records.
+      # @raise [Airbased::Error] If a record is missing an ID, since it is mandatory for update.
+      def update(records, overwrite: false, typecast: false)
+        record_hashes = hash_or_record_to_hash(records, id_required: true)
+
+        record_hashes.each_slice(10).flat_map do |slice|
+          update_slice(slice, overwrite:, typecast:)
+        end
+      end
+
+      # Upserts records in the Airtable base.
+      #
+      # The records parameter can either be an array of Record objects or an array of hashes, where each hash represents a record.
+      #
+      # @param records [Array<Record, Hash>] The records to be upserted. Must be an array of Record objects or hashes.
+      # @param merge_on [Array<String>] The fields to merge on. Must be an array of 1 to 3 field names.
+      # @param overwrite [Boolean] (false) Whether to overwrite existing records. If true, will clear the fields not in the request. Defaults to false.
+      # @param typecast [Boolean] (false) Whether to automatically typecast values. Defaults to false.
+      # @raise [Airbased::Error] If merge_on is not an array of 1 to 3 field names.
+      def upsert(records, merge_on:, overwrite: false, typecast: false)
+        raise Airbased::Error.new("merge_on must be an array of 1 to 3 field names") unless
+          merge_on.is_a?(Array) && merge_on.size.between?(1, 3)
+
+        record_hashes = hash_or_record_to_hash(records)
+
+        record_hashes.each_slice(10).flat_map do |slice|
+          upsert_slice(slice, merge_on:, overwrite:, typecast:)
+        end
+      end
+
+      # Deletes records from the Airtable base.
+      #
+      # The records_or_record_ids parameter can either be an array of Record objects or an array of record IDs.
+      #
+      # @param records_or_record_ids [Array<Record, String>] The records or record IDs to be deleted.
+      # @return [Array<Record>] The IDs of the deleted records.
+      # @raise [Airbased::Error] if an element in the array is neither a Record object nor a String.
+      def delete(records_or_record_ids)
+        responses = records_or_record_ids.each_slice(10).flat_map do |slice|
+          ids = slice.map do |record|
+            if record.is_a?(Record)
+              record.id
+            elsif record.is_a?(String)
+              record
+            else
+              raise Airbased::Error.new("You need to pass an array of records or a record ids but #{record} is a #{record.class}.")
+            end
+          end
+          Airtable.delete("/#{@base_id}/#{table_key}?" + URI.encode_www_form("records[]": ids), options)[:records]
+        end
+        responses.map { |r| r[:id] }
+      end
+
+      private
+
+      # Creates new records in the Airtable base in slices of up to 10 records
+      # from an array of hashes, where each hash represents a record.
+      #
+      # @param slice [Array<Hash>] The slice of records to be created. Each record is represented as a hash.
+      # @return [Array<Record>] An array of Record objects created from the response of the Airtable API.
+      def create_slice(slice, typecast:)
+        records = Airtable.post("/#{@base_id}/#{table_key}", { records: slice, typecast: }, options)[:records]
+        records.map do |record|
+          Record.new(id: record[:id], fields: record[:fields], created_time: record[:created_time], table: self)
+        end
+      end
+
+      def update_slice(slice, overwrite:, typecast:)
+        records = if overwrite
+                    Airtable.put("/#{@base_id}/#{table_key}", { records: slice, typecast: }, options)[:records]
+                  else
+                    Airtable.patch("/#{@base_id}/#{table_key}", { records: slice, typecast: }, options)[:records]
+                  end
+
+        records.map do |record|
+          Record.new(id: record[:id], fields: record[:fields], created_time: record[:created_time], table: self)
+        end
+      end
+
+      def upsert_slice(slice, merge_on:, overwrite:, typecast:)
+        records = if overwrite
+                    Airtable.put("/#{@base_id}/#{table_key}", { perform_upsert: { fields_to_merge_on: merge_on }, records: slice, typecast: }, options)[:records]
+                  else
+                    Airtable.patch("/#{@base_id}/#{table_key}", { perform_upsert: { fields_to_merge_on: merge_on }, records: slice, typecast: }, options)[:records]
+                  end
+
+        records.map do |record|
+          Record.new(id: record[:id], fields: record[:fields], created_time: record[:created_time], table: self)
+        end
+      end
+    end
+  end
+end

data/lib/airbased/table/query.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Airbased
+  class Table
+    # Methods for querying tables.
+    module Query
+      # Fetches a specific record from an Airtable table.
+      #
+      # @param record_id [String] The ID of the record to retrieve.
+      # @return [Record] A record instance with the record data.
+      def find(record_id)
+        # TODO: cellFormat and returnFieldsByFieldId
+        response = Airtable.get("/#{@base_id}/#{table_key}/#{record_id}", nil, options)
+        Record.new(id: response[:id], fields: response[:fields], created_time: response[:created_time], table: self)
+      end
+      alias :get_record :find
+
+      # Fetches the first record from an Airtable table.
+      #
+      # @return [Record, nil] The first record if available, otherwise nil.
+      def first
+        all(page_size: 1, max_records: 1).first
+      end
+
+      def all(
+        offset: nil,
+        page_size: nil,
+        max_records: nil,
+        fields: nil,
+        view: nil,
+        sort: nil,
+        filter_by_formula: nil,
+        time_zone: nil,
+        user_locale: nil,
+        cell_format: nil,
+        return_fields_by_field_id: nil,
+        record_metadata: nil
+      )
+
+        # TODO: required params
+
+        records = []
+
+        loop do
+          result = records_page(
+            offset:, page_size:, max_records:, fields:, view:, sort:, filter_by_formula:,
+            time_zone:, user_locale:, cell_format:, return_fields_by_field_id:, record_metadata:
+          )
+
+          offset = result[:offset]
+          page_records = result[:records]
+          records.concat(page_records)
+          break if offset.nil?
+        end
+        records
+      end
+
+      private
+
+      def records_page(
+        offset: nil,
+        page_size: nil,
+        max_records: nil,
+        fields: nil,
+        view: nil,
+        sort: nil,
+        filter_by_formula: nil,
+        time_zone: nil,
+        user_locale: nil,
+        cell_format: nil,
+        return_fields_by_field_id: nil,
+        record_metadata: nil
+      )
+
+        response = Airtable.post("/#{@base_id}/#{table_key}/listRecords", {
+          offset:, page_size:, max_records:, fields:, view:, sort:, filter_by_formula:,
+          time_zone:, user_locale:, cell_format:, return_fields_by_field_id:, record_metadata:
+        }, options)
+        records = response[:records].map do |record|
+          Record.new(id: record[:id], fields: record[:fields], created_time: record[:created_time], table: self)
+        end
+
+        { offset: response[:offset], records: }
+      end
+    end
+  end
+end

data/lib/airbased/table/table.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Airbased
+  # Represents a table in the Airtable base, and provides a way to interact with it.
+  class Table
+    include Query
+    include Persistence
+
+    attr_accessor :id, :name, :base_id, :api_key, :fields, :primary_field_id, :views, :description
+
+    TABLE_MATCHER = /^tbl[[:alnum:]]+$/
+
+    # Initializes a new Table object.
+    #
+    # @param base_id [String] The ID of the base containing the table.
+    # @param id [String, nil] The ID of the table.
+    # @param name [String, nil] The name of the table.
+    # @param api_key [String, nil] The API key to access the table.
+    # @param fields [Array<Hash>, nil] The list of fields in the table.
+    # @param primary_field_id [String, nil] The ID of the primary field in the table.
+    # @param views [Array<Hash>, nil] The list of views in the table.
+    # @param description [String, nil] The description of the table.
+    #
+    # @raise [Airbased::Error] if both id and name are nil.
+    #
+    # @return [Airbased::Table] A new Table object.
+    def initialize(
+      base_id:,
+      id: nil,
+      name: nil,
+      api_key: nil,
+      fields: nil,
+      primary_field_id: nil,
+      views: nil,
+      description: nil
+    )
+      raise Airbased::Error.new("You need to pass an id or a name for the table") if id.nil? && name.nil?
+
+      @id = id
+      @name = name
+      @base_id = base_id
+      @fields = fields
+      @primary_field_id = primary_field_id
+      @views = views
+      @description = description
+
+      # only define api_key if passed specifically for this table, will otherwise use module's api key
+      @api_key = api_key if api_key
+    end
+
+    # Creates a new record instance associated with the table.
+    #
+    # @param fields [Hash] The fields of the new record.
+    # @return [Record] A new Record object with the provided fields and associated with the current table.
+    def new_record(fields:, id: nil, created_time: nil)
+      Record.new(fields:, id:, created_time:, table: self)
+    end
+
+    def table_key
+      @id || CGI.escape_uri_component(@name)
+    end
+
+    # A shortcut for a hash with a table's api key in requests.
+    #
+    # @return [Hash] Hash with API key, or with nil value if no special api key set for table.
+    def options
+      { api_key: }
+    end
+
+    # Airrecord-style shorthand table definition.
+    # Creates a new Table instance with the provided API key, base ID, and table key (table id or name).
+    #
+    # @param [String] api_key The API key to access the Airtable API.
+    # @param [String] base_id The ID of the Airtable base.
+    # @param [String] table_key The name or id of the table within the base.
+    # @return [Table] A new Table instance.
+    def Airbased.table(api_key, base_id, table_key)
+      table_id = nil
+      table_name = nil
+
+      # Deducing whether the passed key is a name or id.
+      if table_key.match?(TABLE_MATCHER)
+        table_id = table_key
+      else
+        table_name = table_key
+      end
+
+      Table.new(api_key:, base_id:, id: table_id, name: table_name)
+    end
+  end
+end

data/lib/airbased/validation.rb

@@ -0,0 +1,29 @@
+module Airbased
+  # The Validation module provides methods for validating Airtable-related values.
+  module Validation
+    # Converts a hash or record to a hash representation.
+    #
+    # @param value [Array<Hash, Record>] The array of hashes or records to convert.
+    # @param id_required [Boolean] Whether an ID is required for each record.
+    # @return [Array<Hash>] An array of hashes representing the records.
+    # @raise [Airbased::Error] If a record is missing an ID when id_required is true.
+    def hash_or_record_to_hash(value, id_required: false)
+      built_records = value.map do |record_object|
+        if id_required && ((record_object.is_a?(Hash) && record_object&.dig(:id).nil? && record_object&.dig("id").nil?) || (record_object.is_a?(Record) && record_object.new_record?))
+          raise Airbased::Error.new("id in records are mandatory for update. Use upsert with merge_on: for records not yet persisted")
+        end
+
+        if record_object.is_a?(Hash) && (record_object.dig(:fields) || record_object.dig("fields"))
+          new_record(**record_object)
+        elsif record_object.is_a?(Hash)
+          new_record(fields: record_object)
+        elsif record_object.is_a?(Airbased::Record)
+          record_object
+        else
+          raise Airbased::Error.new("You need to pass an array of records or a record hashes but #{record_object} is a #{record_object.class}.")
+        end
+      end
+      built_records.map(&:to_api_hash)
+    end
+  end
+end

data/lib/airbased/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Airbased
+  VERSION = "0.0.1-alpha"
+end

data/lib/airbased.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "time"
+
+require_relative "airbased/version"
+
+require_relative "airbased/airtable/errors"
+require_relative "airbased/airtable/airtable"
+
+require_relative "airbased/validation"
+
+require_relative "airbased/base"
+
+require_relative "airbased/table/query"
+require_relative "airbased/table/persistence"
+require_relative "airbased/table/table"
+
+require_relative "airbased/record/persistence"
+require_relative "airbased/record"
+
+# Airbased is a module for interfacing with the Airtable API.
+module Airbased
+  extend self
+  attr_accessor :api_key, :debug
+
+  class Error < StandardError; end
+end

data/sig/airbased.rbs

@@ -0,0 +1,4 @@
+module Airbased
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: airbased
+version: !ruby/object:Gem::Version
+  version: 0.0.1.pre.alpha
+platform: ruby
+authors:
+- Aleks Lokhmutov
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-08-25 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'
+description:
+email:
+- 43987794+alokhmutov@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- airbased.gemspec
+- lib/airbased.rb
+- lib/airbased/airtable/airtable.rb
+- lib/airbased/airtable/errors.rb
+- lib/airbased/base.rb
+- lib/airbased/record.rb
+- lib/airbased/record/persistence.rb
+- lib/airbased/table/persistence.rb
+- lib/airbased/table/query.rb
+- lib/airbased/table/table.rb
+- lib/airbased/validation.rb
+- lib/airbased/version.rb
+- sig/airbased.rbs
+homepage: https://github.com/alokhmutov/airbased
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/alokhmutov/airbased
+  source_code_uri: https://github.com/alokhmutov/airbased
+  changelog_uri: https://github.com/alokhmutov/airbased/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.17
+signing_key:
+specification_version: 4
+summary: Ruby interface to the Airtable’s API.
+test_files: []