airtable_client 0.1.0

data/lib/airtable_client/table.rb

@@ -0,0 +1,402 @@
+class AirtableClient
+
+  # A table in an Airtable base: querying, single-record CRUD, and batch
+  # operations. Obtain instances via {AirtableClient#table}.
+  #
+  # Each Table holds its own persistent HTTP connection (opened lazily), so
+  # instances are cheap to create and efficient to reuse — but they must not
+  # be shared across threads. All requests pass through the process-global
+  # {RateLimiter} and retry automatically on HTTP 429/503.
+  class Table < Resource
+    # Records fetched per request when paginating with {#all}.
+    LIMIT_MAX = 100
+
+    # Fetches every record in the table, following pagination offsets until
+    # the collection is exhausted (one request per {LIMIT_MAX} records).
+    #
+    # Loads the entire table into memory; for bounded queries use {#select}.
+    #
+    # @param options [Hash] the same options as {#records}
+    # @return [Array<Record>] every record in the table
+    # @raise [Error] when the API returns an error
+    # @example
+    #   table.all(sort: ["Name", :asc])
+    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
+
+    # Fetches one page of records.
+    #
+    # @param options [Hash] query options; any other keys pass through as
+    #   raw query parameters
+    # @option options [Array(String, Symbol)] :sort field name and direction,
+    #   e.g. +["Name", :asc]+
+    # @option options [Integer] :limit maximum records to return (API cap 100)
+    # @option options [String] :offset pagination offset from a previous
+    #   {RecordSet#offset}
+    # @option options [Array<String>] :fields only return these fields
+    # @option options [String] :view scope the query to a view
+    # @return [RecordSet] the page of records plus the next pagination offset
+    # @raise [Error] when the API returns an error
+    # @example
+    #   page = table.records(sort: ["Name", :asc], limit: 50)
+    #   more = table.records(offset: page.offset)
+    def records(options={})
+      options["sortField"], options["sortDirection"] = options.delete(:sort) if options[:sort]
+      options['fields[]'] = options.delete(:fields) if options[:fields]
+      options['view'] = options.delete(:view) if options[:view]
+      request = build_get_request(worksheet_url, query: options)
+      response = perform_request(request)
+      result = parse_response(response)
+      log_response(response, 'GET', parsed_result: result)
+      check_and_raise_error(result, status_code: response.code.to_i)
+      RecordSet.new(result)
+    end
+
+    # Queries records, optionally filtered by an Airtable formula.
+    #
+    # @param options [Hash] query options; any other keys pass through as
+    #   raw query parameters
+    # @option options [String] :formula an Airtable formula, sent as
+    #   +filterByFormula+ — escape user input with
+    #   {AirtableClient.escape_formula_value}
+    # @option options [Array(String, Symbol)] :sort field name and direction
+    # @option options [Integer] :limit maximum records, sent as +maxRecords+
+    # @option options [Array<String>] :fields only return these fields
+    # @option options [String] :view scope the query to a view
+    # @return [RecordSet] the matching records
+    # @raise [ArgumentError] when +:formula+ is not a String
+    # @raise [Error] when the API returns an error
+    # @example
+    #   table.select(formula: "Active = 1", fields: %w[Name Email], limit: 10)
+    def select(options={})
+      options['sortField'], options['sortDirection'] = options.delete(:sort) if options[:sort]
+      options['maxRecords'] = options.delete(:limit) if options[:limit]
+
+      if options[:formula]
+        raise_bad_formula_error unless options[:formula].is_a? String
+        options['filterByFormula'] = options.delete(:formula)
+      end
+
+      options['fields[]'] = options.delete(:fields) if options[:fields]
+      options['view'] = options.delete(:view) if options[:view]
+
+      request = build_get_request(worksheet_url, query: options)
+      response = perform_request(request)
+      result = parse_response(response)
+      log_response(response, 'GET', parsed_result: result)
+      check_and_raise_error(result, status_code: response.code.to_i)
+      RecordSet.new(result)
+    end
+
+    def raise_bad_formula_error
+      raise ArgumentError.new("The value for filter should be a String.")
+    end
+
+    # Fetches a single record by id.
+    #
+    # @param id [String] the record id, e.g. +"rec02sKGVIzU65eV2"+
+    # @return [Record, nil] the record, or nil when the response has no id
+    # @raise [Error] when the API returns an error (type +"NOT_FOUND"+ for
+    #   a missing record)
+    def find(id)
+      request = build_get_request("#{worksheet_url}/#{id}")
+      response = perform_request(request)
+      result = parse_response(response)
+      log_response(response, 'GET', parsed_result: result)
+      check_and_raise_error(result, status_code: response.code.to_i)
+      Record.new(result_attributes(result)) if result.is_a?(Hash) && result["id"]
+    end
+
+    # Creates a record.
+    #
+    # @param record [Record] the record to create
+    # @return [Record] the same record, mutated in place with the assigned
+    #   id and any server-computed fields
+    # @raise [Error] when the API returns an error
+    # @example
+    #   record = AirtableClient::Record.new('Name' => 'Sarah Jaine')
+    #   table.create(record)
+    #   record.id # => "rec03sKOVIzU65eV4"
+    def create(record)
+      request = build_post_request(worksheet_url, body: { "fields" => record.fields })
+      response = perform_request(request)
+      result = parse_response(response)
+      log_response(response, 'POST', parsed_result: result)
+
+      check_and_raise_error(result, status_code: response.code.to_i)
+
+      record.override_attributes!(result_attributes(result))
+      record
+    end
+
+    # Replaces a record (HTTP PUT — destructive). Fields not present on the
+    # given record are cleared server-side; for a partial update use
+    # {#update_record_fields}.
+    #
+    # @param record [Record] a record with an id and the full desired fields
+    # @return [Record] the same record, mutated in place with the response
+    # @raise [Error] when the API returns an error
+    def update(record)
+      request = build_put_request("#{worksheet_url}/#{record.id}", body: { "fields" => record.fields_for_update })
+      response = perform_request(request)
+      result = parse_response(response)
+      log_response(response, 'PUT', parsed_result: result)
+
+      check_and_raise_error(result, status_code: response.code.to_i)
+
+      record.override_attributes!(result_attributes(result))
+      record
+    end
+
+    # Partially updates a record (HTTP PATCH). Only the given fields change;
+    # everything else is left untouched.
+    #
+    # @param record_id [String] the record id
+    # @param fields_for_update [Hash{String => Object}] field name => new value
+    # @return [Record] a new Record built from the response
+    # @raise [Error] when the API returns an error
+    # @example
+    #   table.update_record_fields('rec123', 'Email' => 'new@example.com')
+    def update_record_fields(record_id, fields_for_update)
+      request = build_patch_request("#{worksheet_url}/#{record_id}", body: { "fields" => fields_for_update })
+      response = perform_request(request)
+      result = parse_response(response)
+      log_response(response, 'PATCH', parsed_result: result)
+
+      check_and_raise_error(result, status_code: response.code.to_i)
+
+      Record.new(result_attributes(result))
+    end
+
+    # Deletes a record by id.
+    #
+    # @param id [String] the record id
+    # @return [Hash] the API response, e.g. +{"deleted" => true, "id" => ...}+
+    # @raise [Error] when the API returns an error
+    def destroy(id)
+      request = build_delete_request("#{worksheet_url}/#{id}")
+      response = perform_request(request)
+      result = parse_response(response)
+      log_response(response, 'DELETE', parsed_result: result)
+      check_and_raise_error(result, status_code: response.code.to_i)
+      result
+    end
+
+    # Creates records in bulk, auto-chunking into groups of
+    # {Configuration#batch_size} (default 10) — one request per chunk.
+    #
+    # Does not raise on per-chunk API errors; inspect the returned
+    # {BatchResult} for partial failures.
+    #
+    # @param records [Array<Record>] the records to create
+    # @return [BatchResult] successes and failures across all chunks
+    # @example
+    #   result = table.create_batch(records)
+    #   result.failures.each { |f| warn "#{f[:record].inspect}: #{f[:error].message}" }
+    def create_batch(records)
+      batch_operation(records) do |chunk|
+        body = { "records" => chunk.map { |r| { "fields" => r.fields } } }
+        build_post_request(worksheet_url, body: body)
+      end
+    end
+
+    # Partially updates records in bulk (HTTP PATCH), auto-chunking like
+    # {#create_batch}.
+    #
+    # @param records [Array<Record>] records to update; each must have an id
+    # @return [BatchResult] successes and failures across all chunks
+    def update_batch(records)
+      batch_operation(records) do |chunk|
+        body = { "records" => chunk.map { |r| { "id" => r.id, "fields" => r.fields_for_update } } }
+        build_patch_request(worksheet_url, body: body)
+      end
+    end
+
+    # Deletes records in bulk by id, auto-chunking like {#create_batch}.
+    #
+    # @param record_ids [Array<String>] ids of the records to delete
+    # @return [BatchResult] successes and failures across all chunks
+    def destroy_batch(record_ids)
+      batch_result = BatchResult.new
+      record_ids = Array(record_ids)
+      return batch_result if record_ids.empty?
+
+      record_ids.each_slice(batch_size) do |chunk|
+        query_string = chunk.map { |id| "records[]=#{URI.encode_www_form_component(id)}" }.join("&")
+        request = build_delete_request("#{worksheet_url}?#{query_string}")
+        response = perform_request(request)
+        result = parse_response(response)
+        log_response(response, 'DELETE', parsed_result: result)
+
+        if result.is_a?(Hash) && result['error'].is_a?(Hash)
+          error = Error.new(result['error'], status_code: response.code.to_i)
+          chunk.each { |id| batch_result.add_failure(id, error) }
+        elsif result['records']
+          result['records'].each do |r|
+            if r['deleted']
+              batch_result.add_success(r)
+            else
+              batch_result.add_failure(r['id'], Error.new({ 'type' => 'DELETE_FAILED', 'message' => "Record #{r['id']} was not deleted" }))
+            end
+          end
+        end
+      end
+      batch_result
+    end
+
+    # Upserts records — find-or-create in one call via Airtable's
+    # +performUpsert+. Existing records matching on the merge fields are
+    # updated; the rest are created. Auto-chunks like {#create_batch}.
+    #
+    # @param records [Array<Record>] the records to upsert
+    # @param fields_to_merge_on [Array<String>] 1–3 field names used to match
+    #   existing records
+    # @return [BatchResult] all resulting records in
+    #   {BatchResult#successes}, with {BatchResult#created_record_ids}
+    #   listing the ones that were newly created
+    # @example
+    #   result = table.upsert(records, fields_to_merge_on: ['Email'])
+    #   result.created_record_ids # => ids created rather than updated
+    def upsert(records, fields_to_merge_on:)
+      batch_result = BatchResult.new
+      records = Array(records)
+      return batch_result if records.empty?
+
+      records.each_slice(batch_size) do |chunk|
+        body = {
+          "performUpsert" => { "fieldsToMergeOn" => fields_to_merge_on },
+          "records" => chunk.map { |r| { "fields" => r.fields } }
+        }
+        request = build_patch_request(worksheet_url, body: body)
+        response = perform_request(request)
+        result = parse_response(response)
+        log_response(response, 'PATCH', parsed_result: result)
+
+        if result.is_a?(Hash) && result['error'].is_a?(Hash)
+          error = Error.new(result['error'], status_code: response.code.to_i)
+          chunk.each { |r| batch_result.add_failure(r, error) }
+        else
+          batch_result.add_created_ids(result['createdRecords'] || [])
+          (result['records'] || []).each do |r|
+            batch_result.add_success(Record.new(result_attributes(r)))
+          end
+        end
+      end
+      batch_result
+    end
+
+    protected
+
+    def batch_size
+      AirtableClient.configuration.batch_size
+    end
+
+    def check_and_raise_error(result, status_code: nil)
+      if result.is_a?(Hash) && result['error'].is_a?(Hash)
+        error_hash = result['error']
+        # Preserve Airtable's specific type if present, otherwise classify by status code
+        error_hash['type'] ||= Error::STATUS_CODE_ERROR_TYPES.fetch(status_code, 'UNKNOWN_ERROR')
+        raise Error.new(error_hash, status_code: status_code)
+      end
+
+      # Raise on non-2xx status codes even when the parsed result has no error hash
+      # (or has a non-Hash error value like a string).
+      if status_code && status_code >= 400
+        raise Error.from_response(status_code, nil)
+      end
+    end
+
+    def log_response(response, http_method, parsed_result: nil)
+      status_code = response.code.to_i
+      duration_ms = @last_request_duration_ms || 0
+      request_body_size = @last_request_body_size || 0
+      response_body_size = @last_response_body_size || 0
+      error_hash = parsed_result.is_a?(Hash) && parsed_result['error'].is_a?(Hash) ? parsed_result['error'] : nil
+      error_type = error_hash&.dig('type')
+      error_message = error_hash&.dig('message')
+
+      log_line = "[Airtable] #{status_code} #{http_method} #{worksheet_name} #{duration_ms}ms request=#{request_body_size}b response=#{response_body_size}b"
+      log_line += " error_type=#{error_type} error_message=#{error_message}" if error_type
+
+      emit_log(:info, log_line)
+
+      AirtableClient.configuration.on_request&.call({
+        status_code: status_code,
+        table: worksheet_name,
+        http_method: http_method,
+        duration_ms: duration_ms,
+        request_body_size: request_body_size,
+        response_body_size: response_body_size,
+        error_type: error_type,
+        error_message: error_message
+      })
+    end
+
+    def parse_response(response)
+      body = response.body
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise Error.from_response(response.code.to_i, body)
+    end
+
+    def result_attributes(res)
+      res["fields"].merge("id" => res["id"]) if res.is_a?(Hash) && res["id"]
+    end
+
+    def worksheet_url
+      "#{BASE_PATH}/#{app_token}/#{url_encode(worksheet_name)}"
+    end
+
+    # Shared batch operation logic for create_batch and update_batch.
+    # Yields each chunk to the block which builds the request, then
+    # processes the response into the BatchResult.
+    def batch_operation(records)
+      batch_result = BatchResult.new
+      records = Array(records)
+      return batch_result if records.empty?
+
+      records.each_slice(batch_size) do |chunk|
+        begin
+          request = yield(chunk)
+          response = perform_request(request)
+          result = parse_response(response)
+          http_method = request.method
+          log_response(response, http_method, parsed_result: result)
+
+          if result.is_a?(Hash) && result['error'].is_a?(Hash)
+            error = Error.new(result['error'], status_code: response.code.to_i)
+            chunk.each { |r| batch_result.add_failure(r, error) }
+          elsif result.is_a?(Hash) && result['records']
+            result['records'].each do |r|
+              batch_result.add_success(Record.new(result_attributes(r)))
+            end
+          else
+            chunk.each { |r| batch_result.add_failure(r, Error.new({ 'type' => 'UNEXPECTED_RESPONSE', 'message' => 'Response contained no records or error' })) }
+          end
+        rescue AirtableClient::Error => e
+          chunk.each { |r| batch_result.add_failure(r, e) }
+        end
+      end
+      batch_result
+    end
+
+    # From http://apidock.com/ruby/ERB/Util/url_encode
+    def url_encode(s)
+      s.to_s.dup.force_encoding("ASCII-8BIT").gsub(/[^a-zA-Z0-9_\-.]/) {
+        sprintf("%%%02X", $&.unpack("C")[0])
+      }
+    end
+  end
+
+end

data/lib/airtable_client/version.rb

@@ -0,0 +1,3 @@
+class AirtableClient
+  VERSION = "0.1.0"
+end

data/lib/airtable_client.rb

@@ -0,0 +1,56 @@
+require 'net/http'
+require 'json'
+require 'uri'
+require 'openssl'
+require 'delegate'
+
+# Entry point to the library. Holds the access token and builds {Table}
+# instances.
+#
+# @example
+#   client = AirtableClient.new(ENV.fetch('AIRTABLE_ACCESS_TOKEN'))
+#   table  = client.table('appXXXXXXXXXXXXXX', 'Table Name')
+#   table.all
+class AirtableClient
+  # @param api_key [String] an Airtable personal access token
+  # @param timeout [Integer] HTTP open/read/write timeout in seconds for
+  #   tables built by this client
+  def initialize(api_key, timeout: Resource::DEFAULT_TIMEOUT)
+    @api_key = api_key
+    @timeout = timeout
+  end
+
+  # Builds a {Table} for one table in one base.
+  #
+  # @param app_token [String] the base id, e.g. +"appXXXXXXXXXXXXXX"+
+  # @param worksheet_name [String] the table name (or table id)
+  # @return [Table] a new Table — not thread-safe, so build one per thread
+  def table(app_token, worksheet_name)
+    Table.new(@api_key, app_token, worksheet_name, timeout: @timeout)
+  end
+
+  # Escapes a value for safe interpolation into an Airtable formula string.
+  # Airtable formulas use single-quoted strings; this escapes backslashes
+  # and single quotes, then wraps the value in single quotes. Always use it
+  # when a formula includes user input.
+  #
+  # @param value [#to_s] the raw value
+  # @return [String] the quoted, escaped formula literal
+  # @example
+  #   formula = "{Email} = #{AirtableClient.escape_formula_value(user.email)}"
+  #   table.select(formula: formula)
+  def self.escape_formula_value(value)
+    escaped = value.to_s.gsub('\\', '\\\\\\\\').gsub("'", "\\\\'")
+    "'#{escaped}'"
+  end
+end
+
+require 'airtable_client/version'
+require 'airtable_client/configuration'
+require 'airtable_client/resource'
+require 'airtable_client/record'
+require 'airtable_client/record_set'
+require 'airtable_client/table'
+require 'airtable_client/error'
+require 'airtable_client/rate_limiter'
+require 'airtable_client/batch_result'

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: airtable_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Silva
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  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: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+description: 'Ruby client for the Airtable Web API with zero runtime dependencies:
+  persistent Net::HTTP connections, client-side rate limiting, automatic retries with
+  exponential backoff, error classification, batch operations with auto-chunking,
+  and upsert support.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/airtable_client.rb
+- lib/airtable_client/batch_result.rb
+- lib/airtable_client/configuration.rb
+- lib/airtable_client/error.rb
+- lib/airtable_client/rate_limiter.rb
+- lib/airtable_client/record.rb
+- lib/airtable_client/record_set.rb
+- lib/airtable_client/resource.rb
+- lib/airtable_client/table.rb
+- lib/airtable_client/version.rb
+homepage: https://github.com/Davidslv/airtable_client
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Davidslv/airtable_client
+  changelog_uri: https://github.com/Davidslv/airtable_client/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Davidslv/airtable_client/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: A resilient Ruby client for the Airtable Web API
+test_files: []