airtable-orm 0.1.0

data/lib/airtable/orm/querying.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Airtable
+  module ORM
+    module Querying
+      extend ActiveSupport::Concern
+
+      DEFAULT_PAGE_SIZE = 100
+      DEFAULT_MAX_RECORDS = 1000
+
+      class_methods do
+        # Fetch all records from the table. Always ignores max_records; use +where+ for limits.
+        def all(**options)
+          where(**options, max_records: nil)
+        end
+
+        # Query records with a formula
+        def where(formula: nil, sort: nil, view: nil, fields: nil, max_records: DEFAULT_MAX_RECORDS,
+                  page_size: DEFAULT_PAGE_SIZE)
+          records(formula:, sort:, view:, fields:, max_records:, page_size:)
+        end
+
+        # Fetch the first record matching the criteria
+        def first(formula: nil, sort: nil)
+          where(formula:, sort:, max_records: 1).first
+        end
+
+        # Fetch the last record matching the criteria by reversing the sort order.
+        # NOTE: Unlike ActiveRecord, Airtable has no default sort order.
+        # Calling last without sort returns an arbitrary record (same as first).
+        def last(formula: nil, sort: nil)
+          where(formula:, sort: reverse_sort_order(sort), max_records: 1).first
+        end
+
+        # Find the first record matching attribute conditions.
+        # Example: Airtable::Case.find_by(slug: "abc-123")
+        def find_by(**conditions)
+          raise ArgumentError, "find_by requires at least one condition" if conditions.empty?
+
+          clauses = conditions.map do |field, value|
+            field_id = resolve_field_id(field)
+            "{#{field_id}} = #{format_formula_value(value)}"
+          end
+          formula = clauses.size == 1 ? clauses.first : "AND(#{clauses.join(", ")})"
+          first(formula: formula)
+        end
+
+        # Like find_by but raises RecordNotFound when no match.
+        def find_by!(**conditions)
+          find_by(**conditions) || raise(Airtable::ORM::RecordNotFound,
+                                         "Couldn't find #{name} with #{conditions.inspect}")
+        end
+
+        # Count records without instantiating model objects.
+        # Requests no fields to minimize payload (Airtable has no count-only endpoint).
+        def count(formula: nil)
+          count_records(formula:)
+        end
+
+        # Format a Ruby value for use in an Airtable formula comparison.
+        # Returns the correctly typed formula literal (quoted string, bare number, function call, etc.).
+        def format_formula_value(value)
+          case value
+          when NilClass then "BLANK()"
+          when TrueClass then "TRUE()"
+          when FalseClass then "FALSE()"
+          when Integer, Float then value.to_s
+          when Date then "'#{value.iso8601}'"
+          when Time, DateTime then "'#{value.utc.iso8601}'"
+          else "'#{escape_formula_value(value)}'"
+          end
+        end
+
+        # Escape a value for use in an Airtable formula string literal.
+        # Handles backslashes, single quotes, and control characters.
+        def escape_formula_value(value)
+          value.to_s
+               .gsub("\\", "\\\\\\\\")  # backslashes first
+               .gsub("'", "\\\\'")      # single quotes
+               .gsub("\n", "\\n")       # newlines
+               .gsub("\r", "\\r")       # carriage returns
+               .gsub("\t", "\\t")       # tabs
+        end
+
+        private
+
+        # Fetch records from the API
+        def records(formula: nil, sort: nil, view: nil, fields: nil, max_records: nil, page_size: nil, offset: nil,
+                    paginate: true)
+          all_records = []
+
+          each_page(formula:, sort:, view:, fields:, max_records:, page_size:, offset:, paginate:) do |page|
+            all_records.concat(page.map { |record_data| instantiate_from_api_response(record_data) })
+          end
+
+          Airtable::ORM::Collection.new(all_records, model_class: self)
+        end
+
+        # Count records without instantiating model objects.
+        def count_records(formula: nil)
+          total = 0
+          each_page(formula:, fields: []) { |page| total += page.size }
+          total
+        end
+
+        # Paginate through listRecords, yielding each page's raw records array.
+        def each_page(formula: nil, sort: nil, view: nil, fields: nil, max_records: nil, page_size: nil, offset: nil,
+                      paginate: true)
+          current_offset = offset
+
+          loop do
+            options = build_query_options(formula:, sort:, view:, fields:, max_records:, page_size:,
+                                          offset: current_offset)
+            response = client.connection.post(api_path("listRecords"), options)
+            parsed_response = response.body
+
+            Airtable::ORM::Http::Client.raise_api_error(response.status, parsed_response) unless response.success?
+
+            yield parsed_response["records"]
+
+            break unless paginate && parsed_response["offset"]
+
+            current_offset = parsed_response["offset"]
+          end
+        end
+
+        # Build query options for the API
+        def build_query_options(formula:, sort:, view:, fields:, max_records:, page_size:, offset:)
+          {
+            returnFieldsByFieldId: true,
+            filterByFormula: formula,
+            sort: sort && normalize_sort_options(sort),
+            view: view,
+            fields: fields && resolve_field_ids(fields),
+            maxRecords: max_records,
+            pageSize: page_size,
+            offset: offset
+          }.compact
+        end
+
+        # Normalize sort options to Airtable API format
+        # Accepts: { field: :asc } or [[:field1, :desc], [:field2, :asc]]
+        # Converts symbol attributes to their Airtable field IDs
+        def normalize_sort_options(sort)
+          return [] unless sort.respond_to?(:map)
+
+          sort.map { |field, direction| { field: resolve_field_id(field), direction: direction.to_s } }
+        end
+
+        # Resolve symbol attribute to Airtable field ID
+        # If the field is already a string, return it as-is (assuming it's a valid field ID)
+        # If it's a symbol, look up the field ID from the attribute map and validate it exists
+        def resolve_field_id(field)
+          return field.to_s unless field.is_a?(Symbol)
+
+          field_id = field_mapping[field]
+          return field_id if field_id
+
+          # Raise error for unknown field symbols to prevent silent API errors
+          valid_fields = field_mapping.keys.join(", ")
+          raise ArgumentError, "Unknown field: #{field.inspect}. Valid fields: #{valid_fields}"
+        end
+
+        # Resolve an array of fields (symbols or strings) to field IDs
+        def resolve_field_ids(fields)
+          fields.map { |field| resolve_field_id(field) }
+        end
+
+        # Reverse sort order for last() method
+        def reverse_sort_order(sort)
+          return nil unless sort
+
+          flip = ->(dir) { dir.to_sym == :asc ? :desc : :asc }
+
+          case sort
+          when Hash then sort.transform_values(&flip)
+          when Array then sort.map { |field, dir| [field, flip.call(dir)] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/airtable/orm/schema.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Airtable
+  module ORM
+    class Schema
+      CACHE_KEY = "airtable:schema"
+      CACHE_EXPIRY = 24.hours
+
+      class << self
+        def fetch(base_id, force_refresh: false)
+          clear_cache(base_id) if force_refresh
+
+          cache.fetch(cache_key(base_id), expires_in: CACHE_EXPIRY) { fetch_from_api(base_id) }
+        end
+
+        def clear_cache(base_id)
+          cache.delete(cache_key(base_id))
+        end
+
+        private
+
+        def required_table_ids
+          ORM.config.table_ids
+        end
+
+        def fetch_from_api(base_id)
+          response = client.connection.get("/v0/meta/bases/#{base_id}/tables")
+          parsed_response = response.body
+
+          if response.success?
+            indexed_schema(parsed_response)
+          else
+            Http::Client.raise_api_error(response.status, parsed_response)
+          end
+        end
+
+        def indexed_schema(parsed_response)
+          tables = parsed_response.deep_symbolize_keys[:tables]
+
+          # Filter only required tables
+          tables.select! { |table| required_table_ids.include?(table[:id]) }
+
+          # Transform fields into hash indexed by field id
+          tables.each do |table|
+            table[:fields] = table[:fields].index_by { |field| field[:id] }
+          end
+
+          # Index tables by table id
+          tables.index_by { |table| table[:id] }
+        end
+
+        def cache_key(base_id)
+          "#{CACHE_KEY}:#{base_id}"
+        end
+
+        def cache
+          ORM.config.cache
+        end
+
+        def client
+          Http::Client.default
+        end
+      end
+    end
+  end
+end

data/lib/airtable/orm/testing/stub_helpers.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Airtable
+  module ORM
+    # Opt-in RSpec test support: `require "airtable/orm/testing"`. Depends on rspec-mocks at
+    # runtime, which is why the directory is ignored by the gem's Zeitwerk loader.
+    module Testing
+      class << self
+        # Absolute path to a JSON dump of /v0/meta/bases/:id/tables — the host points this at
+        # its own fixture before using stub_airtable_schema.
+        attr_accessor :schema_fixture_path
+      end
+
+      # Include into RSpec (`config.include Airtable::ORM::Testing::StubHelpers, :airtable`)
+      # and call stub_airtable_http_client in a before hook — no HTTP leaves the process.
+      module StubHelpers
+        # Stub schema fetch to use the fixture file instead of the /v0/meta API.
+        # Returns the same schema data for all fetch calls, so tests work regardless
+        # of which base they're configured for.
+        def stub_airtable_schema
+          path = Testing.schema_fixture_path
+          raise ArgumentError, "Set Airtable::ORM::Testing.schema_fixture_path first" unless path
+
+          raw_schema = JSON.parse(File.read(path))
+          indexed_schema = Airtable::ORM::Schema.send(:indexed_schema, raw_schema)
+
+          allow(Airtable::ORM::Schema).to receive(:fetch).and_return(indexed_schema)
+        end
+
+        # Route every request through a Faraday test adapter (returned for stubbing) and
+        # bypass the API-key check in Http::Client.default with a real client instance so
+        # escape/other helpers keep working.
+        def stub_airtable_http_client
+          @stubs = Faraday::Adapter::Test::Stubs.new
+
+          stub_connection = Faraday.new do |builder|
+            builder.request :json
+            builder.response :json
+            builder.adapter :test, @stubs
+          end
+
+          fake_client = Airtable::ORM::Http::Client.new("test_api_key")
+          allow(fake_client).to receive(:connection).and_return(stub_connection)
+          allow(Airtable::ORM::Http::Client).to receive(:default).and_return(fake_client)
+
+          stub_airtable_schema
+
+          @stubs
+        end
+      end
+    end
+  end
+end

data/lib/airtable/orm/testing.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "testing/stub_helpers"

data/lib/airtable/orm/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Airtable
+  module ORM
+    VERSION = "0.1.0"
+  end
+end

data/lib/airtable/orm.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "active_model"
+require "active_support"
+# The lib leans broadly on AS core exts standalone (pluck, deep_symbolize_keys, 24.hours,
+# truncate…) — active_model's transitive requires load only a tiny subset.
+require "active_support/core_ext"
+require "faraday"
+require "faraday/net_http_persistent"
+require "logger"
+require "time"
+
+module Airtable; end
+
+loader = Zeitwerk::Loader.for_gem_extension(Airtable)
+loader.inflector.inflect("orm" => "ORM")     # orm.rb / orm/ → ORM, not Orm
+loader.ignore("#{__dir__}/orm/errors.rb")    # one file, many constants — required eagerly below
+# RSpec-dependent test support, opt-in via require "airtable/orm/testing".
+loader.ignore("#{__dir__}/orm/testing.rb", "#{__dir__}/orm/testing")
+loader.setup
+
+module Airtable
+  module ORM
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config
+      end
+
+      # True when an API key is configured — hosts gate network-touching hooks on this.
+      def configured?
+        config.api_key.present?
+      end
+
+      def reset!
+        @config = nil
+        Http::Client.reset!
+      end
+    end
+  end
+end
+
+require_relative "orm/errors"

data/lib/airtable-orm.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Bundler.require resolves the dashed gem name to this file.
+require_relative "airtable/orm"

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: airtable-orm
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Roman Sklenar
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http_persistent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: CRUD, query DSL, associations, schema introspection, batch updates and
+  rate limiting for Airtable — behind a branded error hierarchy that never leaks the
+  underlying HTTP client.
+email:
+- mail@romansklenar.cz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/airtable-orm.rb
+- lib/airtable/orm.rb
+- lib/airtable/orm/associations.rb
+- lib/airtable/orm/attributes.rb
+- lib/airtable/orm/base.rb
+- lib/airtable/orm/batch_result.rb
+- lib/airtable/orm/collection.rb
+- lib/airtable/orm/configuration.rb
+- lib/airtable/orm/core.rb
+- lib/airtable/orm/errors.rb
+- lib/airtable/orm/http/client.rb
+- lib/airtable/orm/http/error_handler.rb
+- lib/airtable/orm/http/rate_limiter.rb
+- lib/airtable/orm/persistence.rb
+- lib/airtable/orm/querying.rb
+- lib/airtable/orm/schema.rb
+- lib/airtable/orm/testing.rb
+- lib/airtable/orm/testing/stub_helpers.rb
+- lib/airtable/orm/version.rb
+homepage: https://github.com/romansklenar/airtable-orm
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/romansklenar/airtable-orm
+  source_code_uri: https://github.com/romansklenar/airtable-orm
+  changelog_uri: https://github.com/romansklenar/airtable-orm/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/romansklenar/airtable-orm/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.12
+specification_version: 4
+summary: ActiveModel-style ORM for the Airtable API
+test_files: []