airtable-orm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 22ca62058d684f1b34fbf154b50afb7c8a5c37659b5235fef23614f97642d6c1
+  data.tar.gz: 554987924ef0c43b3692adc311cdf72dd367d927e9396f92af7dc4ba1a2f12d5
+SHA512:
+  metadata.gz: 52e3f9c34c7f34d6ffa17e2f85ebc97a072917611bac555ee300852c6b20799dd22c448485e69e07ab3d14cf85b88984fb6d52c054893b2a0f24e980293e2bfb
+  data.tar.gz: bc2d2694f67595eac95ba645056ff3d2e9778d38dcf072737fd8312a2677eb046dbddbf9414238994f0f9c7f0a9d10c7f343a7f1fb7f97c32279e131b03818bd

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-07-10
+
+Initial release — the generic Airtable client/ORM extracted from the EUCS Mono application:
+
+- `Airtable::ORM::Base` with the attribute DSL, querying (formula building, automatic pagination),
+  persistence (incl. `update_many` batching with `BatchResult`), associations with preloading,
+  and schema introspection cached via the injected store.
+- Host-agnostic configuration through `Airtable::ORM.configure` (API key, base/table/field IDs,
+  timeouts, rate limit, loggers, schema cache — in-process `MemoryCache` by default).
+- Branded error hierarchy (`ApiError`, its deliberate sibling `ConnectionError`, ActiveRecord-style
+  record errors) — the underlying HTTP client never leaks to consumers.
+- Client-side rate limiting (5 requests/s per base) and fail-fast timeouts on a persistent
+  Faraday connection.
+- Opt-in RSpec test support (`airtable/orm/testing`): Faraday test adapter wiring and
+  schema-fixture stubbing.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Roman Sklenar
+
+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,121 @@
+# Airtable::ORM
+
+An ActiveModel-style ORM for the [Airtable API](https://airtable.com/developers/web/api/introduction): CRUD, a query DSL with formula building, associations with preloading, schema introspection, batch updates and client-side rate limiting — behind a branded error hierarchy that never leaks the underlying HTTP client.
+
+```ruby
+class Order < Airtable::ORM::Base
+  self.table_name = :order
+
+  attribute :email, :string
+  attribute :state, :string
+
+  belongs_to :client, class_name: "Client", foreign_key: :client_ids
+end
+
+Order.where(formula: "AND({State} = 'Active')").each { |order| puts order.email }
+Order.find_by(email: "jane@example.com")&.update(state: "Closed")
+```
+
+## Installation
+
+```ruby
+# Gemfile
+gem "airtable-orm"
+```
+
+## Configuration
+
+The gem never reads `Rails.*`, `ENV`, or credentials itself — every host touchpoint is injected:
+
+```ruby
+# e.g. config/initializers/airtable.rb in a Rails app
+Airtable::ORM.configure do |config|
+  config.api_key      = Rails.application.credentials.dig(:airtable, :api_key)
+  config.base_id      = "appXXXXXXXXXXXXXX"
+  config.tables       = {
+    order: {
+      id: "tblXXXXXXXXXXXXXX",
+      fields: { _id: "id", email: "fldXXXXXXXXXXXXXX", state: "fldYYYYYYYYYYYYYY" }
+    }
+  }
+  config.cache        = Rails.cache    # schema cache; defaults to an in-process MemoryCache
+  config.logger       = Rails.logger   # defaults to a null logger
+end
+```
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `api_key` | — (required) | Airtable personal access token |
+| `base_id` | — (required) | The base your models live in |
+| `tables` | `{}` | `table_name => { id:, fields: { attribute => field_id } }` map |
+| `api_url` | `https://api.airtable.com` | API endpoint |
+| `open_timeout` / `read_timeout` | `5` / `10` seconds | Fail fast instead of hanging a worker |
+| `rate_limit` | `5` | Requests/second per base (Airtable throttles for 30 s above 5) |
+| `logger` | null logger | Batch-update failure reporting |
+| `http_logger` | `nil` | Set to a `Logger` to log Faraday requests |
+| `cache` | in-process `MemoryCache` | Schema cache; anything responding to `fetch`/`delete` |
+
+`Airtable::ORM.configured?` returns whether an `api_key` is set — handy for gating enqueue hooks so test/CI environments never touch the network.
+
+## Models
+
+```ruby
+class Case < Airtable::ORM::Base
+  self.table_name = :case               # key into config.tables
+
+  attribute :label, :string
+  attribute :potential, :big_integer
+  attribute :tags, :airtable_array      # multipleSelects / multipleRecordLinks
+  attribute :client_ids, :airtable_array
+
+  has_many :clients, class_name: "Client", foreign_key: :client_ids
+end
+```
+
+- **Querying:** `all`, `where(formula:, sort:, max_records:)`, `first`, `find`, `find_many`, `find_by`/`find_by!`, `count`. Symbol conditions build (and escape) Airtable formulas; pagination is automatic.
+- **Persistence:** `save`/`save!`, `create`/`create!`, `update`/`update!`, `destroy`, `reload`, plus `Model.update_many(records)` batching 10 per PATCH with a `BatchResult` (`updated`/`skipped`/`failed`).
+- **Associations:** `has_many`/`belongs_to` readers, writers, `add_*`/`remove_*`, memoization and `Collection#preload` for eager loading.
+- **Schema:** table/field metadata from `/v0/meta/bases`, cached via `config.cache`; `Model.field_options(:state)` reads select options.
+- **`#url`** — deeplink to the record in the Airtable UI.
+- **`normalizes`** — available on ActiveModel 8.0+ (the DSL doesn't exist in 7.1).
+
+## Errors
+
+Consumers rescue `Airtable::ORM::*` only — the HTTP client (Faraday today) never leaks, so swapping transports is not a breaking change.
+
+| Error | Raised when |
+| --- | --- |
+| `Airtable::ORM::ApiError` | Airtable answered with an error (rate limit, 5xx, validation) |
+| `Airtable::ORM::ConnectionError` | The request never completed (timeout, DNS, TLS) — a **sibling** of `ApiError`, so `save`'s `rescue ApiError => false` never swallows an outage |
+| `Airtable::ORM::RecordNotFound` / `RecordInvalid` / `RecordNotSaved` / `RecordNotDestroyed` / `RecordNotPersisted` | ActiveRecord-style persistence failures |
+| `Airtable::ORM::UnknownFieldError` / `InvalidAttributeError` | Mapping problems |
+
+All error classes are defined eagerly at require time, so `retry_on Airtable::ORM::ConnectionError` in a class body needs no extra `require`.
+
+## Test support
+
+```ruby
+# spec_helper.rb
+require "airtable/orm/testing"
+
+Airtable::ORM::Testing.schema_fixture_path = "spec/fixtures/airtable.schema.json"
+
+RSpec.configure do |config|
+  config.include Airtable::ORM::Testing::StubHelpers, :airtable
+  config.before(:each, :airtable) { stub_airtable_http_client }
+end
+```
+
+`stub_airtable_http_client` routes every request through a Faraday test adapter (returned for stubbing) and serves schema lookups from your fixture — no HTTP leaves the process.
+
+## Development
+
+`mise install` (or any Ruby ≥ 3.2), `bin/setup`, then `bundle exec rake` (specs + RuboCop). Release: bump `lib/airtable/orm/version.rb`, update `CHANGELOG.md`, `bundle exec rake release`.
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/romansklenar/airtable-orm>.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/airtable/orm/associations.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Airtable
+  module ORM
+    module Associations
+      extend ActiveSupport::Concern
+
+      # Requires Attributes concern. Uses read_raw_attribute/write_raw_attribute to
+      # bypass accessors and avoid infinite recursion when association names match attributes.
+
+      included do
+        class_attribute :defined_associations, instance_writer: false, default: {}
+      end
+
+      private
+
+      # Read linked record IDs from a foreign key, with optional reversal for Airtable UI order.
+      # Airtable's API returns record links in reverse order compared to the UI.
+      # By default we reverse to match the UI order.
+      def read_linked_ids(foreign_key, reverse: true)
+        ids = read_raw_attribute(foreign_key) || []
+        reverse ? ids.reverse : ids
+      end
+
+      # Set memoized value directly (used by preloading)
+      def write_association_cache(name, value)
+        instance_variable_set(:"@_memo_#{name}", value)
+      end
+
+      # Memoize association loading with automatic cache management
+      def memoize_association(name)
+        ivar = :"@_memo_#{name}"
+        return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+        instance_variable_set(ivar, yield)
+      end
+
+      # Clear memoization cache for an association
+      def clear_association_cache(name)
+        ivar = :"@_memo_#{name}"
+        remove_instance_variable(ivar) if instance_variable_defined?(ivar)
+      end
+
+      # Extract ID from a record object or return the ID string as-is
+      def extract_association_id(record_or_id)
+        record_or_id.respond_to?(:id) ? record_or_id.id : record_or_id
+      end
+
+      class_methods do
+        # Airtable returns linked IDs in reverse UI order; we reverse on read/write to match.
+        def has_many(association_name, class_name:, foreign_key:)
+          self.defined_associations = defined_associations.merge(
+            association_name => { type: :has_many, class_name: class_name, foreign_key: foreign_key }
+          )
+
+          define_method(association_name) do
+            memoize_association(association_name) do
+              ids = read_linked_ids(foreign_key)
+              klass = class_name.constantize
+              ids.empty? ? Airtable::ORM::Collection.new([], model_class: klass) : klass.find_many(ids)
+            end
+          end
+
+          define_method("#{association_name}=") do |records|
+            ids = Array(records).map { |record| extract_association_id(record) }
+            write_raw_attribute(foreign_key, ids.reverse)
+            clear_association_cache(association_name)
+          end
+
+          define_method("add_#{association_name.to_s.singularize}") do |record|
+            current_ids = read_linked_ids(foreign_key, reverse: false)
+            add_id = extract_association_id(record)
+            write_raw_attribute(foreign_key, [add_id] + current_ids)
+            clear_association_cache(association_name)
+          end
+
+          define_method("remove_#{association_name.to_s.singularize}") do |record|
+            current_ids = read_linked_ids(foreign_key, reverse: false)
+            remove_id = extract_association_id(record)
+
+            write_raw_attribute(foreign_key, current_ids - [remove_id])
+            clear_association_cache(association_name)
+          end
+        end
+
+        def belongs_to(association_name, class_name:, foreign_key:)
+          self.defined_associations = defined_associations.merge(
+            association_name => { type: :belongs_to, class_name: class_name, foreign_key: foreign_key }
+          )
+
+          define_method(association_name) do
+            memoize_association(association_name) do
+              id = read_linked_ids(foreign_key).first
+              id ? class_name.constantize.find(id) : nil
+            end
+          end
+
+          define_method("#{association_name}=") do |record|
+            if record.nil?
+              write_raw_attribute(foreign_key, [])
+            else
+              id = extract_association_id(record)
+              write_raw_attribute(foreign_key, [id])
+            end
+
+            clear_association_cache(association_name)
+          end
+        end
+
+        # In Airtable, linked record fields are stored as ID arrays on both sides,
+        # so has_one and belongs_to are functionally identical (unlike ActiveRecord
+        # where they differ in which side holds the foreign key).
+        alias_method :has_one, :belongs_to
+
+        # Eager-load associations to avoid N+1 API calls.
+        def preload(records, *association_names)
+          return if records.empty?
+
+          association_names.each do |name|
+            config = defined_associations[name]
+            raise ArgumentError, "Unknown association: #{name.inspect}" unless config
+
+            klass = config[:class_name].constantize
+            fk = config[:foreign_key]
+            many = config[:type] == :has_many
+
+            preload_association(records, name, klass, fk, many: many)
+          end
+        end
+
+        def preload_association(records, association_name, klass, foreign_key, many:)
+          all_ids = if many
+                      records.flat_map { |r| r.send(:read_linked_ids, foreign_key) }.uniq
+                    else
+                      records.filter_map { |r| r.send(:read_linked_ids, foreign_key).first }.uniq
+                    end
+
+          fetched_by_id = all_ids.empty? ? {} : klass.find_many(all_ids).index_by(&:id)
+
+          records.each do |record|
+            ids = record.send(:read_linked_ids, foreign_key)
+            value = if many
+                      Airtable::ORM::Collection.new(ids.filter_map { |id| fetched_by_id[id] }, model_class: klass)
+                    else
+                      fetched_by_id[ids.first]
+                    end
+            record.send(:write_association_cache, association_name, value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/airtable/orm/attributes.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Airtable
+  module ORM
+    module Attributes
+      extend ActiveSupport::Concern
+
+      included do
+        include ActiveModel::Attributes
+        # The `normalizes` DSL ships with ActiveModel 8.0+; on 7.1 models simply don't have it.
+        include ActiveModel::Attributes::Normalization if defined?(ActiveModel::Attributes::Normalization)
+        include ActiveModel::Dirty
+
+        # Full symbol → field_id mapping from config/airtable.yml (includes ALL fields).
+        # Use field_mapping instead, which filters to only declared attributes.
+        class_attribute :config_field_mapping, instance_writer: false, default: {}
+      end
+
+      # Special read-only attributes that are not part of the Airtable fields
+      READ_ONLY_ATTRIBUTES = %i[id created_at].freeze
+
+      class_methods do
+        # Set the logical table name (symbol) for this model.
+        # This triggers config field mapping from config.
+        def table_name=(symbol)
+          @table_name = symbol.to_sym
+          define_field_mapping
+        end
+
+        def table_name
+          @table_name
+        end
+
+        # Filtered mapping: only symbols that have a declared `attribute` in the model.
+        # Lazily computed on first access (after class body has been evaluated).
+        def field_mapping
+          @field_mapping ||= config_field_mapping.select { |symbol, _| attribute_types.key?(symbol.to_s) }
+        end
+
+        # Get the Airtable table ID for this model
+        def table_id
+          ORM.config.table_id(table_name)
+        end
+
+        # Get schema for this table
+        # Memoized at class level to avoid repeated cache lookups
+        def schema
+          return {} unless table_name
+
+          @schema ||= Airtable::ORM::Schema.fetch(base_id)[table_id]
+        end
+
+        # Clear the memoized schema cache
+        # Useful for testing or when the schema changes
+        def clear_schema_cache
+          @schema = nil
+          @field_mapping = nil
+        end
+
+        # Get field schema by symbol
+        def field_schema(symbol)
+          field_id = field_mapping[symbol.to_sym]
+          return nil unless field_id
+
+          schema.dig(:fields, field_id)
+        end
+
+        # Extract select options from schema for singleSelect and multipleSelects fields
+        # Returns a hash mapping field symbols to their available options
+        #
+        # @return [Hash{Symbol => Array<String>}] Field symbols mapped to option arrays
+        # @example
+        #   Airtable::Case.schema_options
+        #   # => { state: ["Open", "Closed"], scope: ["Inquiry", "Claim"], ... }
+        #
+        # @example Accessing specific field options
+        #   Airtable::Case.schema_options[:state]
+        #   # => ["Open", "Closed", "Archived"]
+        def schema_options
+          return {} unless field_mapping.present?
+
+          field_mapping.each_with_object({}) do |(symbol, field_id), options|
+            field_info = schema.dig(:fields, field_id)
+            next unless field_info
+
+            case field_info[:type]
+            when "singleSelect", "multipleSelects"
+              choices = field_info.dig(:options, :choices)
+              options[symbol] = choices.map { |choice| choice[:name] } if choices
+            end
+          end
+        end
+
+        # Get options for a specific select field
+        # @param field_symbol [Symbol] The field symbol (e.g., :category, :state)
+        # @return [Array<String>] Array of available options for the field
+        # @example
+        #   Airtable::Case.field_options(:category)
+        #   # => ["Personal Injury", "Property", "Business"]
+        def field_options(field_symbol)
+          schema_options[field_symbol.to_sym] || []
+        end
+
+        private
+
+        # Build config_field_mapping (symbol → field_id) from config.
+        # Stores ALL config fields; field_mapping lazily filters to declared attributes.
+        def define_field_mapping
+          fields = ORM.config.table_fields(table_name)
+          self.config_field_mapping = fields&.except(:_id) || {}
+        end
+      end
+
+      # Override [] to use symbol keys only
+      def [](key)
+        validate_symbol_key!(key)
+
+        # Handle special read-only attributes
+        return read_special_attribute(key) if special_attribute?(key)
+
+        validate_regular_attribute!(key)
+        public_send(key)
+      end
+
+      # Override []= to use symbol keys only
+      def []=(key, value)
+        validate_symbol_key!(key)
+        validate_not_readonly!(key)
+        validate_regular_attribute!(key)
+
+        public_send("#{key}=", value)
+      end
+
+      # @api private — Direct access to @attributes, bypassing accessor methods.
+      # Used by Associations to avoid infinite recursion when association name matches the attribute.
+      def read_raw_attribute(key)
+        return nil unless attribute_defined?(key)
+
+        @attributes[key.to_s]&.value
+      end
+
+      # @api private — Direct write to @attributes, maintaining Dirty tracking.
+      def write_raw_attribute(key, value)
+        return unless attribute_defined?(key)
+
+        @attributes.write_from_user(key.to_s, value)
+      end
+
+      # Get all attributes as a hash with symbol keys.
+      # Delegates to ActiveModel::Attributes#attributes which returns the same data with string keys.
+      def symbol_attributes
+        attributes.symbolize_keys
+      end
+
+      # Non-nil attributes with field IDs as keys (for CREATE).
+      def fields_for_create
+        map_attributes(key_type: :field_id, exclude_nil: true)
+      end
+
+      # Changed attributes with field IDs as keys (for UPDATE). Includes nil values.
+      def fields_for_update
+        map_attributes(key_type: :field_id, filter: ->(symbol) { changed.include?(symbol.to_s) })
+      end
+
+      def map_attributes(key_type:, exclude_nil: false, filter: nil)
+        return {} unless self.class.field_mapping
+
+        self.class.field_mapping.each_with_object({}) do |(symbol, field_id), hash|
+          next if filter && !filter.call(symbol)
+
+          value = read_raw_attribute(symbol)
+          next if exclude_nil && value.nil?
+
+          key = key_type == :symbol ? symbol : field_id
+          hash[key] = value
+        end
+      end
+
+      # Validate that key is a symbol
+      def validate_symbol_key!(key)
+        return if key.is_a?(Symbol)
+
+        raise Airtable::ORM::InvalidAttributeError, "Only symbol keys are supported (e.g., record[:email])"
+      end
+
+      # Validate that key is not a read-only attribute
+      def validate_not_readonly!(key)
+        return unless READ_ONLY_ATTRIBUTES.include?(key)
+
+        raise Airtable::ORM::InvalidAttributeError, "Cannot set read-only attribute: #{key.inspect}"
+      end
+
+      # Validate that key is a known regular attribute (not special attributes like :id, :created_at)
+      def validate_regular_attribute!(key)
+        return if attribute_defined?(key)
+
+        raise Airtable::ORM::UnknownFieldError, "Unknown field symbol: #{key.inspect}"
+      end
+
+      # Check if this is a special read-only attribute
+      def special_attribute?(key)
+        READ_ONLY_ATTRIBUTES.include?(key)
+      end
+
+      # Read a special read-only attribute value
+      def read_special_attribute(key)
+        case key
+        when :id then @id
+        when :created_at then @created_at
+        end
+      end
+
+      # Check if attribute is defined (explicitly declared in the model class body)
+      def attribute_defined?(symbol)
+        self.class.attribute_types.key?(symbol.to_s)
+      end
+
+      # Custom type for Airtable arrays (handles record links and multi-selects)
+      class AirtableArrayType < ActiveModel::Type::Value
+        def cast(value)
+          case value
+          when Array then value
+          when nil then []
+          else [value]
+          end
+        end
+
+        def serialize(value)
+          cast(value)
+        end
+      end
+
+      ActiveModel::Type.register(:airtable_array, AirtableArrayType)
+    end
+  end
+end

data/lib/airtable/orm/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Load error classes and value objects first
+require_relative "errors"
+require_relative "batch_result"
+
+module Airtable
+  module ORM
+    class Base
+      include ActiveModel::Model
+      include Core
+      include Attributes
+      include Persistence
+      include Querying
+      include Associations
+
+      # Callback support
+      extend ActiveModel::Callbacks
+
+      class << self
+        # Get the base ID from config
+        def base_id
+          ORM.config.base_id
+        end
+      end
+
+      # Public deeplink to this record in the Airtable UI.
+      def url
+        "https://airtable.com/#{self.class.base_id}/#{self.class.table_id}/#{id}"
+      end
+    end
+  end
+end

data/lib/airtable/orm/batch_result.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Airtable
+  module ORM
+    # Holds the result of a batch update operation.
+    #
+    # @attr updated [Array] Records that were successfully sent to the API and updated
+    # @attr skipped [Array] Records that had no changes and were not sent to the API
+    # @attr failed [Array] Records that failed validation or API call
+    BatchResult = Struct.new(:updated, :skipped, :failed, keyword_init: true) do
+      def initialize(updated: [], skipped: [], failed: [])
+        super
+      end
+
+      def none_failed?
+        failed.empty?
+      end
+
+      def any_failed?
+        failed.any?
+      end
+
+      def total_count
+        updated.size + skipped.size + failed.size
+      end
+    end
+  end
+end

data/lib/airtable/orm/collection.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Airtable
+  module ORM
+    # Thin wrapper around Array that enables chainable preloading.
+    #
+    #   cases = Airtable::Case.all.preload(:clients)
+    #   active = cases.select { |c| c[:state] == "Active" }.preload(:advisors)
+    #
+    # Filtering methods (select, reject, sort_by) return new Collections,
+    # preserving the ability to chain preload.
+    class Collection < DelegateClass(Array)
+      attr_reader :model_class
+
+      def initialize(records, model_class:)
+        super(records)
+        @model_class = model_class
+      end
+
+      # Eager-load associations for every record in the collection.
+      # Returns +self+ so calls can be chained.
+      def preload(*names)
+        model_class.preload(self, *names)
+        self
+      end
+
+      def select(&block)
+        return super unless block
+
+        self.class.new(super, model_class: model_class)
+      end
+
+      def reject(&block)
+        return super unless block
+
+        self.class.new(super, model_class: model_class)
+      end
+
+      def sort_by(&block)
+        return super unless block
+
+        self.class.new(super, model_class: model_class)
+      end
+    end
+  end
+end