airtable-orm 0.1.0

data/lib/airtable/orm/configuration.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Airtable
+  module ORM
+    # Every host touchpoint is injected here — the gem never reads Rails.*, ENV, or
+    # credentials itself. Wired by the host application via Airtable::ORM.configure
+    # (in Rails typically from an initializer, inside to_prepare).
+    class Configuration
+      attr_accessor :api_key, :base_id, :tables, :api_url,
+                    :open_timeout, :read_timeout, :rate_limit,
+                    :logger, :http_logger, :cache
+
+      def initialize
+        @tables = {}
+        @api_url = "https://api.airtable.com"
+        @open_timeout = 5
+        @read_timeout = 10
+        @rate_limit = 5                # Airtable throttles for 30 seconds above 5 requests/s per base
+        @logger = Logger.new(IO::NULL)
+        @http_logger = nil             # set to a Logger to enable Faraday request logging
+        @cache = MemoryCache.new       # schema cache default; hosts inject Rails.cache
+      end
+
+      # Example: table_fields(:case) => { _id: "id", advisors: "fldgU5KU1qlN8eJ3v", ... }
+      def table_fields(table_name)
+        tables.dig(table_name.to_sym, :fields)
+      end
+
+      # Example: table_id(:case) => "tblQeKH7yYesvWf5p"
+      def table_id(table_name)
+        tables.dig(table_name.to_sym, :id)
+      end
+
+      def table_ids
+        tables.values.pluck(:id)
+      end
+
+      # Default in-process schema cache so an unconfigured consumer doesn't hit the /v0/meta
+      # API on every Schema.fetch (and burn the 5 RPS budget on metadata). Hosts inject a real
+      # store (Rails.cache); this one honours only :expires_in. The mutex is held across the
+      # fetch block (all keys serialize behind it, and nesting fetch calls would deadlock) —
+      # fine for the rare schema refresh this exists for.
+      class MemoryCache
+        def initialize
+          @mutex = Mutex.new
+          @store = {}
+        end
+
+        def fetch(key, expires_in: nil)
+          @mutex.synchronize do
+            # Hit/miss by key presence, not value truthiness — false/nil are cacheable
+            # (matching Rails.cache semantics).
+            if (entry = @store[key])
+              value, expires_at = entry
+              return value if expires_at.nil? || Time.now < expires_at
+            end
+
+            yield.tap { |fresh| @store[key] = [fresh, expires_in && (Time.now + expires_in)] }
+          end
+        end
+
+        def delete(key)
+          @mutex.synchronize { @store.delete(key) }
+        end
+      end
+    end
+  end
+end

data/lib/airtable/orm/core.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Airtable
+  module ORM
+    module Core
+      extend ActiveSupport::Concern
+
+      # Instance comparison
+      def ==(other)
+        return false unless other.is_a?(self.class)
+        return false if new_record? || other.new_record?
+
+        id == other.id
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, id].hash
+      end
+
+      # Inspect method for better debugging
+      def inspect
+        attribute_string = self.class.attribute_types.map do |name, _type|
+          value = read_raw_attribute(name.to_sym)
+          "#{name}: #{value.inspect}"
+        end.join(", ")
+
+        "#<#{self.class.name} id: #{id.inspect}, #{attribute_string}>"
+      end
+
+      # Convert to hash with symbol keys
+      def to_h
+        {
+          id: id,
+          created_at: created_at,
+          **symbol_attributes
+        }
+      end
+
+      # Freeze the record
+      def freeze
+        @id.freeze
+        @created_at.freeze
+        super
+      end
+    end
+  end
+end

data/lib/airtable/orm/errors.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Airtable
+  module ORM
+    # Base error class for all Airtable-related errors
+    class Error < StandardError; end
+
+    # Raised when a record cannot be found
+    class RecordNotFound < Error; end
+
+    # Raised when trying to access an unknown field
+    class UnknownFieldError < Error; end
+
+    # Raised when an invalid attribute is provided
+    class InvalidAttributeError < Error; end
+
+    # Raised when a record fails validation.
+    # Use the #record method to retrieve the record which did not validate.
+    class RecordInvalid < Error
+      attr_reader :record
+
+      def initialize(record = nil)
+        if record
+          @record = record
+          errors = @record.errors.full_messages.join(", ")
+          super("Validation failed: #{errors}")
+        else
+          super("Record invalid")
+        end
+      end
+    end
+
+    # Raised when trying to perform operations on a non-persisted record
+    # (e.g., trying to destroy or reload a new record)
+    class RecordNotPersisted < Error; end
+
+    # Raised when trying to save a new record that fails
+    class RecordNotSaved < Error; end
+
+    # Raised when a record cannot be destroyed
+    class RecordNotDestroyed < Error; end
+
+    # Raised when API communication fails
+    class ApiError < Error
+      attr_reader :status, :response
+
+      def initialize(message, status: nil, response: nil)
+        super(message)
+        @status = status
+        @response = response
+      end
+    end
+
+    # Raised when the request never completed — a read timeout, dropped/failed connection, TLS error,
+    # etc. — mapped from the raw transport error by Airtable::ORM::Http::ErrorHandler so callers only
+    # ever deal in Airtable::* exceptions, never the HTTP client's. Deliberately a sibling of ApiError,
+    # not a subclass: the API never responded, so it isn't an "API error". Being outside the ApiError
+    # branch also means persistence's `rescue ApiError` ignores it, so a blip propagates (to retry)
+    # instead of being swallowed into a `false` save.
+    class ConnectionError < Error; end
+  end
+end

data/lib/airtable/orm/http/client.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "rate_limiter"
+require_relative "error_handler"
+
+module Airtable
+  module ORM
+    module Http
+      class Client
+        attr_reader :api_key
+
+        # Shared client instance with credential validation.
+        # Used by Persistence and Schema to avoid duplicating client/key setup.
+        def self.default
+          @default ||= begin
+            key = ORM.config.api_key
+            if key.blank?
+              raise Airtable::ORM::Error,
+                    "Airtable API key is missing. Set api_key via Airtable::ORM.configure."
+            end
+
+            new(key)
+          end
+        end
+
+        def self.reset!
+          @default = nil
+        end
+
+        def initialize(api_key)
+          @api_key = api_key
+        end
+
+        def connection
+          @connection ||= Faraday.new(url: api_uri, headers: headers) do |builder|
+            builder.options.open_timeout = ORM.config.open_timeout
+            builder.options.timeout = ORM.config.read_timeout
+            # Outermost middleware so its rescue wraps every inner handler and the adapter — maps raw
+            # Faraday transport errors to Airtable::ORM::ConnectionError before they leave the client.
+            builder.request :airtable_error_handler
+            builder.request :json
+            builder.request :airtable_rate_limiter, requests_per_second: ORM.config.rate_limit
+            builder.response :json
+            builder.adapter :net_http_persistent
+
+            if (http_logger = ORM.config.http_logger)
+              builder.response :logger, http_logger, bodies: { request: true, response: false }, headers: false,
+                                                     errors: true, log_level: :debug
+            end
+          end
+        end
+
+        def api_uri
+          @api_uri ||= URI.parse(ORM.config.api_url)
+        end
+
+        def headers
+          {
+            "Authorization" => "Bearer #{api_key}",
+            "Content-Type" => "application/json",
+            "User-Agent" => "airtable-orm/#{VERSION}"
+          }
+        end
+
+        def escape(string)
+          ERB::Util.url_encode(string)
+        end
+
+        # Parse an Airtable API error response and raise an ApiError.
+        def self.raise_api_error(status, error)
+          type = (error.is_a?(Hash) && error.dig("error", "type")) || "Communication error"
+          msg = case error
+                when Hash then error.dig("error", "message")
+                when String then error
+                when NilClass then "invalid or empty response body (not valid JSON)"
+                else error.inspect
+                end
+
+          raise Airtable::ORM::ApiError.new("HTTP #{status}: #{type}: #{msg.to_s.truncate(200, omission: "…")}",
+                                            status: status, response: error)
+        end
+      end
+    end
+  end
+end

data/lib/airtable/orm/http/error_handler.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Airtable
+  module ORM
+    module Http
+      # Maps the whole Faraday::Error family to Airtable::ORM::ConnectionError so no Faraday type
+      # leaks past the client (rationale on the class in error.rb). Safe to catch the base: we don't
+      # enable Faraday's :raise_error, so HTTP 4xx/5xx come back as responses (→ Airtable::ORM::ApiError
+      # downstream), never raised through here. The original error is kept as #cause.
+      class ErrorHandler < Faraday::Middleware
+        def call(env)
+          @app.call(env)
+        rescue Faraday::Error => e
+          raise Airtable::ORM::ConnectionError, "Airtable request failed: #{e.class}: #{e.message}"
+        end
+      end
+    end
+  end
+end
+
+Faraday::Request.register_middleware(
+  airtable_error_handler: Airtable::ORM::Http::ErrorHandler
+)

data/lib/airtable/orm/http/rate_limiter.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Airtable
+  module ORM
+    module Http
+      class RateLimiter < Faraday::Middleware
+        def initialize(app, requests_per_second: nil, sleeper: nil)
+          super(app)
+          @rps = requests_per_second
+          @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+          @mutex = Mutex.new
+          @requests = []
+        end
+
+        def call(env)
+          @mutex.synchronize do
+            wait if too_many_requests_in_last_second?
+            @requests << Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            @requests.shift if @rps && @requests.size > @rps
+          end
+          @app.call(env)
+        end
+
+        def clear
+          @mutex.synchronize { @requests = [] }
+        end
+
+        private
+
+        def too_many_requests_in_last_second?
+          return false unless @rps
+          return false unless @requests.size >= @rps
+
+          window_span < 1.0
+        end
+
+        def wait
+          wait_time = 1.0 - window_span
+          @sleeper.call(wait_time)
+        end
+
+        def window_span
+          @requests.last - @requests.first
+        end
+      end
+    end
+  end
+end
+
+Faraday::Request.register_middleware(
+  airtable_rate_limiter: Airtable::ORM::Http::RateLimiter
+)

data/lib/airtable/orm/persistence.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Airtable
+  module ORM
+    module Persistence
+      extend ActiveSupport::Concern
+
+      included do
+        attr_reader :id, :created_at
+
+        # Track if this record has been persisted to Airtable
+        define_model_callbacks :save, :create, :update, :destroy
+      end
+
+      BATCH_SIZE = 10
+      MAX_FIND_MANY_IDS = 500
+
+      class_methods do
+        # Batch update records (up to 10 per API request).
+        # Triages locally: new/invalid → failed, unchanged → skipped, changed → sent.
+        def update_many(records)
+          result = Airtable::ORM::BatchResult.new
+
+          pending = []
+          records.each do |record|
+            if record.new_record? || record.invalid?
+              result.failed << record
+            elsif !record.changed?
+              record.clear_changes_information
+              result.skipped << record
+            else
+              pending << record
+            end
+          end
+
+          pending.each_slice(BATCH_SIZE) do |batch|
+            send_batch_update(batch, result)
+          end
+
+          result
+        end
+
+        # Get the API client
+        def client
+          Airtable::ORM::Http::Client.default
+        end
+
+        # Build API path for this table (appends returnFieldsByFieldId=true).
+        def api_path(resource_id = nil)
+          base_path = "/v0/#{ORM.config.base_id}/#{client.escape(table_id)}"
+          full_path = resource_id ? "#{base_path}/#{resource_id}" : base_path
+          "#{full_path}?returnFieldsByFieldId=true"
+        end
+
+        # Find a record by ID
+        def find(id)
+          response = client.connection.get(api_path(id))
+          parsed_response = response.body
+
+          if response.success?
+            instantiate_from_api_response(parsed_response)
+          else
+            Airtable::ORM::Http::Client.raise_api_error(response.status, parsed_response)
+          end
+        rescue Airtable::ORM::ApiError => e
+          raise Airtable::ORM::RecordNotFound, "Couldn't find record with id=#{id}" if e.status == 404
+
+          raise
+        end
+
+        # Find multiple records by IDs, preserving order.
+        # Uses an OR formula (single API request) and sorts in memory.
+        def find_many(ids)
+          return Airtable::ORM::Collection.new([], model_class: self) if ids.empty?
+
+          validated_ids = validate_record_ids(ids)
+
+          if validated_ids.size > MAX_FIND_MANY_IDS
+            raise ArgumentError, "find_many supports at most #{MAX_FIND_MANY_IDS} IDs (got #{validated_ids.size})"
+          end
+
+          position_hash = validated_ids.each_with_index.to_h
+
+          or_args = validated_ids.map { |id| "RECORD_ID() = '#{id}'" }.join(",")
+          formula = "OR(#{or_args})"
+          where(formula: formula).sort_by { |record| position_hash[record.id] || validated_ids.length }
+        end
+
+        # Create a new record and save it
+        def create(attributes = {})
+          record = new(attributes)
+          record.save
+          record
+        end
+
+        # Create a new record and save it, raising an error if validation fails
+        def create!(attributes = {})
+          record = new(attributes)
+          record.save!
+          record
+        end
+
+        # Instantiate a record from API response
+        def instantiate_from_api_response(response)
+          data = response.with_indifferent_access
+          symbol_attrs = fields_to_symbol_attributes(data[:fields])
+
+          record = new(**symbol_attrs)
+          record.send(:assign_persistence_state,
+                      id: data[:id],
+                      created_at: data[:createdTime] ? Time.iso8601(data[:createdTime].to_s) : nil,
+                      persisted: true)
+          record.clear_changes_information
+
+          record
+        end
+
+        # Convert API field IDs to symbol attributes.
+        # field_mapping already contains only declared attributes.
+        def fields_to_symbol_attributes(fields)
+          return {} unless fields.is_a?(Hash)
+
+          field_mapping.each_with_object({}) do |(symbol, field_id), hash|
+            hash[symbol] = fields[field_id] if fields.key?(field_id)
+          end
+        end
+
+        private
+
+        # Send a single batch PATCH request to Airtable.
+        def send_batch_update(batch, result)
+          body = {
+            records: batch.map { |record| { id: record.id, fields: record.fields_for_update } }
+          }
+
+          response = client.connection.patch(api_path, body)
+          parsed = response.body
+
+          if response.success?
+            parsed = parsed.with_indifferent_access if parsed.is_a?(Hash)
+            response_records = parsed[:records] || []
+            response_by_id = response_records.index_by { |r| r[:id] }
+
+            batch.each do |record|
+              record_data = response_by_id[record.id]
+              if record_data
+                record.send(:apply_response_fields, record_data)
+                result.updated << record
+              else
+                result.failed << record
+              end
+            end
+          else
+            batch.each { |record| result.failed << record }
+            error_message = parsed.is_a?(Hash) ? parsed.with_indifferent_access.dig(:error, :message) : parsed
+            ORM.config.logger.error(
+              "Airtable batch update failed: HTTP #{response.status}: #{error_message.to_s.truncate(200)}"
+            )
+          end
+        rescue Airtable::ORM::ApiError => e
+          batch.each { |record| result.failed << record }
+          ORM.config.logger.error("Airtable batch update error: #{e.message}")
+        end
+
+        # Validate that record IDs match Airtable's format to prevent formula injection
+        # Airtable record IDs follow the pattern: rec + alphanumeric characters
+        def validate_record_ids(ids)
+          ids.map do |id|
+            id_str = id.to_s
+            unless id_str.match?(/\Arec[a-zA-Z0-9_-]+\z/)
+              raise ArgumentError,
+                    "Invalid Airtable record ID: #{id_str.inspect}"
+            end
+
+            id_str
+          end
+        end
+      end
+
+      # Initialize a record with symbol attributes
+      # Usage: new(email: "test@example.com", first_name: "John")
+      def initialize(**attributes)
+        # Initialize as a new record (not persisted, not destroyed)
+        @id = nil
+        @created_at = nil
+        @persisted = false
+        @destroyed = false
+        @previously_new_record = false
+
+        # Initialize ActiveModel::Attributes
+        super()
+
+        # Set attributes using ActiveModel's assign_attributes
+        assign_attributes(attributes) if attributes.present?
+      end
+
+      # Check if this is a new record (not yet saved)
+      def new_record?
+        !@persisted && !@destroyed
+      end
+
+      # Check if this record has been saved
+      def persisted?
+        @persisted == true
+      end
+
+      # Check if this record has been destroyed
+      def destroyed?
+        @destroyed == true
+      end
+
+      # Check if this record was new before the last save
+      def previously_new_record?
+        @previously_new_record == true
+      end
+
+      # Save the record (create or update)
+      def save(validate: true)
+        return false if validate && invalid?
+
+        result = run_callbacks(:save) do
+          new_record? ? create_record : update_record
+        end
+
+        result != false
+      rescue Airtable::ORM::ApiError
+        false
+      end
+
+      # Save the record, raising an error if it fails.
+      # Unlike save, lets ApiError propagate with full error details.
+      def save!(validate: true)
+        raise Airtable::ORM::RecordInvalid, self if validate && invalid?
+
+        result = run_callbacks(:save) do
+          new_record? ? create_record : update_record
+        end
+
+        raise Airtable::ORM::RecordNotSaved, "Failed to save the record" if result == false
+
+        true
+      end
+
+      # Update attributes and save
+      def update(attributes)
+        assign_attributes(attributes)
+        save
+      end
+
+      # Update attributes and save, raising an error if it fails
+      def update!(attributes)
+        assign_attributes(attributes)
+        save!
+      end
+
+      # Destroy the record
+      def destroy
+        raise Airtable::ORM::RecordNotDestroyed, "Cannot destroy a new record" if new_record?
+
+        run_callbacks :destroy do
+          response = client.connection.delete(self.class.api_path(id))
+          parsed_response = response.body
+
+          if response.success?
+            @persisted = false
+            @destroyed = true
+            freeze
+            self
+          else
+            Airtable::ORM::Http::Client.raise_api_error(response.status, parsed_response)
+          end
+        end
+      end
+
+      # Reload the record from the API
+      def reload
+        raise Airtable::ORM::RecordNotPersisted, "Cannot reload a new record" if new_record?
+
+        fresh_record = self.class.find(id)
+
+        # Copy attributes from fresh record using raw attribute access
+        self.class.attribute_types.each_key do |name|
+          write_raw_attribute(name.to_sym, fresh_record.read_raw_attribute(name.to_sym))
+        end
+
+        @created_at = fresh_record.created_at
+        clear_changes_information
+
+        self
+      end
+
+      # Assign persistence metadata (id, created_at, persisted flag)
+      def assign_persistence_state(id:, created_at:, persisted:)
+        @id = id
+        @created_at = created_at
+        @persisted = persisted
+      end
+
+      # Apply response fields from a create, update, or batch operation.
+      # Uses changes_applied (not clear_changes_information) so after_save
+      # callbacks can inspect previous_changes / saved_change_to_*? methods.
+      def apply_response_fields(data)
+        @previously_new_record = new_record?
+
+        data = data.with_indifferent_access
+        symbol_attrs = self.class.fields_to_symbol_attributes(data[:fields])
+        symbol_attrs.each { |key, value| write_raw_attribute(key, value) }
+
+        assign_persistence_state(
+          id: data[:id],
+          created_at: data[:createdTime] ? Time.iso8601(data[:createdTime].to_s) : nil,
+          persisted: true
+        )
+        changes_applied
+      end
+
+      def client
+        self.class.client
+      end
+
+      # Handle API response from create/update operations
+      def handle_persistence_response(response)
+        parsed = response.body
+
+        if response.success?
+          apply_response_fields(parsed)
+        else
+          Airtable::ORM::Http::Client.raise_api_error(response.status, parsed)
+        end
+      end
+
+      # Create a new record via API
+      def create_record
+        run_callbacks :create do
+          body = { fields: fields_for_create }
+          response = client.connection.post(self.class.api_path, body)
+          handle_persistence_response(response)
+          true
+        end
+      end
+
+      # Update only changed fields via PATCH. Fields changed TO nil are sent
+      # (to clear them in Airtable); unchanged nil fields are not sent.
+      def update_record
+        unless changed?
+          clear_changes_information
+          return true
+        end
+
+        run_callbacks :update do
+          body = { fields: fields_for_update }
+          response = client.connection.patch(self.class.api_path(id), body)
+          handle_persistence_response(response)
+          true
+        end
+      end
+    end
+  end
+end