airtable_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eeda5df571d963886f3ff4a2875c7571fcbdce7f123b4aab42c63ee195aa8d15
+  data.tar.gz: 6df2779eddb32879cfef700caebdfeed3d489646b8926e1789a08ad897525ef5
+SHA512:
+  metadata.gz: 44396ef7a183abc528738f152e141563cfca588cbc726f6dcd6ccb68087e5f31e760385f554ca4c9274099c79f6f5aef6c0e47460fe5ab3b4ae6c4c28a81cdc4
+  data.tar.gz: bd6a6ea475f522913a4864e13a1538d8753c7ec85321fcbee371fe3fb238a61cfb655268d7112f7bc464ab43eb8ccf3940d8b6aecfac6adfbc5900f19e0cd870

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-30
+
+First release under the `airtable_client` name. This gem is a fork of
+[nesquena/airtable-ruby](https://github.com/nesquena/airtable-ruby), heavily
+reworked.
+
+### Added
+
+- Contract-drift watch: `tools/extract_api_contract.rb` snapshots Airtable's
+  published OpenAPI contract into `docs/api/.contract/`, and a weekly
+  workflow opens an `api-drift` issue when the live contract diverges.
+- Credential-gated live smoke suite (`bundle exec rake smoke`) exercising a
+  real record round-trip; runs weekly once the smoke secrets are configured
+  and skips cleanly until then.
+- Client-side thread-safe sliding-window rate limiter: 5 requests per second
+  per base.
+- Automatic retry on HTTP 429 and 503 with exponential backoff and full jitter
+  (maximum 3 attempts).
+- Automatic reconnect on dropped connections.
+- Error classification via `AirtableClient::Error`, exposing `type` and
+  `status_code`, with type names matching airtable.js status-code types.
+- Batch create, update, and delete with automatic chunking (configurable
+  via `batch_size`, default 10) and
+  `BatchResult` partial-failure reporting.
+- Upsert support via `performUpsert`.
+- Formula-value escaping helper: `AirtableClient.escape_formula_value`.
+- Pluggable configuration via `AirtableClient.configure`: a logger and an
+  `on_request` instrumentation callback.
+
+### Changed
+
+- Namespace renamed from `Airtable` to `AirtableClient`, and the gem from
+  `airtable` to `airtable_client`. `AirtableClient.new(token)` replaces
+  `Airtable::Client.new(token)`; nested classes move with it
+  (`AirtableClient::Table`, `AirtableClient::Error`). The gem no longer
+  conflicts with the `airtable` gem.
+- HTTP transport replaced: HTTParty removed in favour of Ruby's built-in
+  `Net::HTTP`, with persistent connections.
+- The gem now has zero runtime dependencies and requires Ruby >= 3.1 (tested
+  on 3.1, 3.2, 3.3, and 3.4).
+
+### Removed
+
+- ActiveSupport runtime dependency.
+- NewRelic and Rails coupling.
+
+[unreleased]: https://github.com/Davidslv/airtable_client/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Davidslv/airtable_client/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,23 @@
+Copyright (c) 2015 Nathan Esquenazi
+Copyright (c) 2016 Airtable
+
+MIT License
+
+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,211 @@
+# airtable_client
+
+[![CI](https://github.com/Davidslv/airtable_client/actions/workflows/ci.yml/badge.svg)](https://github.com/Davidslv/airtable_client/actions/workflows/ci.yml)
+
+A resilient Ruby client for the [Airtable Web API](https://airtable.com/developers/web/api/introduction) with **zero runtime dependencies**.
+
+Built on the Ruby standard library (`Net::HTTP`), with the operational behaviour you need when Airtable sits in a production path:
+
+- **Persistent connections** — each table keeps a keep-alive connection, reconnecting transparently when it drops
+- **Client-side rate limiting** — a thread-safe sliding-window limiter holds you under Airtable's 5 requests/second/base cap instead of bouncing off 429s
+- **Automatic retries** — HTTP 429/503 responses retry up to 3 times with exponential backoff and full jitter
+- **Error classification** — every API error raises `AirtableClient::Error` with a `type` (matching [airtable.js](https://github.com/Airtable/airtable.js) naming) and `status_code`
+- **Batch operations** — create/update/delete in bulk with automatic chunking (configurable, default 10 per request) and per-record partial-failure reporting
+- **Upsert** — find-or-create in one call via Airtable's `performUpsert`
+- **Pluggable observability** — bring your own logger and metrics via `AirtableClient.configure`
+
+## Contents
+
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [Reading records](#reading-records)
+- [Writing records](#writing-records)
+- [Batch operations](#batch-operations)
+- [Error handling](#error-handling)
+- [Configuration](#configuration)
+- [Thread safety](#thread-safety)
+- [Staying in sync with the Airtable API](#staying-in-sync-with-the-airtable-api)
+- [Documentation](#documentation)
+- [Development](#development)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'airtable_client'
+```
+
+Or install directly:
+
+```console
+$ gem install airtable_client
+```
+
+Requires Ruby 3.1+.
+
+### Moving from the `airtable` gem
+
+`airtable_client` uses its own namespace, so it does not conflict with the old
+`airtable` gem. Table and record methods keep their names. Change the entry
+points:
+
+| `airtable` gem | `airtable_client` |
+| --- | --- |
+| `require 'airtable'` | `require 'airtable_client'` |
+| `Airtable::Client.new(token)` | `AirtableClient.new(token)` |
+| `Airtable::Error` | `AirtableClient::Error` |
+
+## Authentication
+
+Create a [personal access token](https://airtable.com/create/tokens) with the scopes you need (typically `data.records:read` and `data.records:write`) and access to your base. Keep it out of source control — read it from the environment:
+
+```ruby
+require 'airtable_client'
+
+client = AirtableClient.new(ENV.fetch('AIRTABLE_ACCESS_TOKEN'))
+table  = client.table('appXXXXXXXXXXXXXX', 'Table Name')
+```
+
+## Reading records
+
+```ruby
+# One page (up to 100 records), with sorting
+records = table.records(sort: ['Name', :asc], limit: 50)
+records.first[:name]  # => "Bill Lowry"
+records.offset        # => pagination offset for the next page
+
+# Every record in the table (paginates for you)
+all = table.all(sort: ['Name', :asc])
+
+# Filter with a formula, select specific fields, scope to a view
+active = table.select(
+  formula: 'Active = 1',
+  fields: %w[Name Email],
+  view: 'Main View',
+  sort: ['Order', 'asc']
+)
+
+# A single record by id
+record = table.find('rec02sKGVIzU65eV2')
+```
+
+When interpolating user input into a formula, escape it:
+
+```ruby
+formula = "{Email} = #{AirtableClient.escape_formula_value(user_email)}"
+table.select(formula: formula)
+```
+
+## Writing records
+
+```ruby
+# Create
+record = AirtableClient::Record.new(name: 'Sarah Jaine', email: 'sarah@jaine.com')
+table.create(record)
+record.id  # => "rec03sKOVIzU65eV4"
+
+# Full replace (PUT)
+record[:email] = 'sarahjaine@updated.com'
+table.update(record)
+
+# Partial update (PATCH) — only the given fields change
+table.update_record_fields('rec03sKOVIzU65eV4', 'Email' => 'new@example.com')
+
+# Delete
+table.destroy('rec03sKOVIzU65eV4')
+```
+
+## Batch operations
+
+Batch methods chunk into groups of `AirtableClient.configuration.batch_size` — default 10, Airtable's long-documented per-request maximum — and return an `AirtableClient::BatchResult` instead of raising on partial failure:
+
+```ruby
+records = names.map { |n| AirtableClient::Record.new(name: n) }
+result  = table.create_batch(records)
+
+result.successes  # => [AirtableClient::Record, ...]
+result.failures   # => [[record, AirtableClient::Error], ...]
+
+table.update_batch(records)      # PATCH, records need ids
+table.destroy_batch(record_ids)  # by id
+```
+
+### Upsert
+
+```ruby
+result = table.upsert(records, fields_to_merge_on: ['Email'])
+result.created_record_ids  # ids that were newly created rather than updated
+```
+
+## Error handling
+
+API failures raise `AirtableClient::Error`:
+
+```ruby
+begin
+  table.find('recDoesNotExist')
+rescue AirtableClient::Error => e
+  e.type         # => "NOT_FOUND" (Airtable's type when given, else classified from the status)
+  e.status_code  # => 404
+  e.message      # => "Record not found"
+end
+```
+
+Types follow airtable.js: `AUTHENTICATION_REQUIRED` (401), `NOT_AUTHORIZED` (403), `NOT_FOUND` (404), `INVALID_REQUEST` (422), `TOO_MANY_REQUESTS` (429), `SERVER_ERROR` (500), `SERVICE_UNAVAILABLE` (503). Note that 429/503 are retried automatically before they ever raise.
+
+## Configuration
+
+```ruby
+AirtableClient.configure do |config|
+  # Anything responding to debug/info/warn. Without one, info/warn lines
+  # go to $stderr and debug (connection lifecycle) is suppressed.
+  config.logger = Logger.new($stdout)
+
+  # Records per batch request (default 10). Airtable's docs no longer state
+  # the cap — verify empirically before raising this.
+  config.batch_size = 10
+
+  # Called after every API response — wire up metrics here.
+  config.on_request = lambda do |event|
+    # event: { status_code:, table:, http_method:, duration_ms:,
+    #          request_body_size:, response_body_size:,
+    #          error_type:, error_message: }
+    StatsD.increment('airtable.request', tags: ["status:#{event[:status_code]}"])
+  end
+end
+```
+
+## Thread safety
+
+- `AirtableClient::Table` holds a persistent connection and is **not** thread-safe — give each thread its own instance.
+- The rate limiter is process-global, thread-safe, and shared across all tables keyed by base, so concurrent threads collectively respect the 5 rps/base limit.
+
+## Staying in sync with the Airtable API
+
+Two weekly scheduled workflows guard against silent drift between this gem and the live API:
+
+- **Contract drift** re-extracts Airtable's published OpenAPI contract (`ruby tools/extract_api_contract.rb`) and compares it to the committed snapshot in `docs/api/.contract/`. Divergence opens an [`api-drift` issue](https://github.com/Davidslv/airtable_client/issues?q=label%3Aapi-drift) containing the diff.
+- **Live smoke** (`bundle exec rake smoke`) runs a real record round-trip — create, find, update, batch, upsert, delete — against a dedicated throwaway base. Failure opens a [`smoke-failure` issue](https://github.com/Davidslv/airtable_client/issues?q=label%3Asmoke-failure). It is credential-gated and never runs on pull requests.
+
+Green silence on Monday mornings means the documented contract is unchanged and the gem still works against the real thing.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) — the guided tour
+- [How-to recipes](docs/how-to.md) — Rails/Sidekiq, testing your app, pagination, partial batch failures
+- [Architecture](docs/architecture.md) — how the gem is built and why
+- [Airtable Web API reference](docs/api/) — the official API contract, extracted locally
+
+## Development
+
+```console
+$ bundle install
+$ bundle exec rake   # runs the minitest suite (WebMock — no live API calls)
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for conventions and [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
+
+## Acknowledgements
+
+Forked from [nesquena/airtable-ruby](https://github.com/nesquena/airtable-ruby) by Nathan Esquenazi and Alexander Sorokin, then substantially reworked: HTTParty replaced with persistent `Net::HTTP`, rate limiting, retries, error classification, batch/upsert support, and the removal of all runtime dependencies. Released under the [MIT License](LICENSE.txt).

data/lib/airtable_client/batch_result.rb

@@ -0,0 +1,55 @@
+class AirtableClient
+  # The outcome of a batch operation ({Table#create_batch},
+  # {Table#update_batch}, {Table#destroy_batch}, {Table#upsert}).
+  #
+  # Batch operations send one request per chunk of
+  # {Configuration#batch_size} records and never raise on per-chunk API
+  # errors — successes and failures are collected here so the caller decides
+  # how to handle partial failure.
+  #
+  # @example
+  #   result = table.create_batch(records)
+  #   unless result.all_succeeded?
+  #     result.failures.each { |f| retry_later(f[:record], f[:error]) }
+  #   end
+  class BatchResult
+    # @return [Array<Record>] records the API accepted (for destroy_batch:
+    #   the raw response hashes of deleted records)
+    attr_reader :successes
+
+    # @return [Array<Hash>] one +{ record:, error: }+ hash per failed input;
+    #   +:record+ is the original input (a {Record} or, for destroy_batch,
+    #   an id string) and +:error+ is the {Error}
+    attr_reader :failures
+
+    # @return [Array<String>] for {Table#upsert} only: ids of records that
+    #   were newly created rather than updated
+    attr_reader :created_record_ids
+
+    def initialize
+      @successes = []
+      @failures = []
+      @created_record_ids = []
+    end
+
+    # @api private
+    def add_success(record)
+      @successes << record
+    end
+
+    # @api private
+    def add_failure(record_or_input, error)
+      @failures << { record: record_or_input, error: error }
+    end
+
+    # @api private
+    def add_created_ids(ids)
+      @created_record_ids.concat(ids)
+    end
+
+    # @return [Boolean] true when no input failed
+    def all_succeeded?
+      @failures.empty?
+    end
+  end
+end

data/lib/airtable_client/configuration.rb

@@ -0,0 +1,75 @@
+class AirtableClient
+  # Process-global gem configuration, set through {AirtableClient.configure}.
+  #
+  # @example
+  #   AirtableClient.configure do |config|
+  #     config.logger = Rails.logger
+  #     config.on_request = ->(event) { StatsD.increment('airtable.request', tags: event) }
+  #     config.batch_size = 10
+  #   end
+  class Configuration
+    # Records per request for batch operations — Airtable's long-documented
+    # per-request maximum.
+    DEFAULT_BATCH_SIZE = 10
+
+    # Any object responding to +debug+/+info+/+warn+ (e.g. a +::Logger+).
+    # When nil (the default), info and warn messages are written to $stderr
+    # and debug messages (connection lifecycle) are suppressed.
+    #
+    # @return [Object, nil]
+    attr_accessor :logger
+
+    # Optional callable invoked after every API response — the hook for
+    # wiring metrics (StatsD, OpenTelemetry, NewRelic, ...). Receives one
+    # event hash: +{ status_code:, table:, http_method:, duration_ms:,
+    # request_body_size:, response_body_size:, error_type:, error_message: }+.
+    #
+    # @return [#call, nil]
+    attr_accessor :on_request
+
+    # How many records batch operations send per request (default
+    # {DEFAULT_BATCH_SIZE}). The current API docs no longer state the cap,
+    # so this is configurable — verify empirically before raising it, as
+    # oversized batches are rejected by the API.
+    #
+    # @return [Integer]
+    attr_reader :batch_size
+
+    def initialize
+      @logger = nil
+      @on_request = nil
+      @batch_size = DEFAULT_BATCH_SIZE
+    end
+
+    # @param value [Integer] a positive number of records per batch request
+    # @raise [ArgumentError] unless value is a positive Integer
+    def batch_size=(value)
+      unless value.is_a?(Integer) && value.positive?
+        raise ArgumentError, "batch_size must be a positive Integer, got #{value.inspect}"
+      end
+
+      @batch_size = value
+    end
+  end
+
+  class << self
+    # @return [Configuration] the process-global configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the global configuration for setup.
+    #
+    # @yieldparam config [Configuration]
+    # @example
+    #   AirtableClient.configure { |config| config.logger = Logger.new($stdout) }
+    def configure
+      yield(configuration)
+    end
+
+    # Restores the default configuration. Mainly useful in tests.
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/airtable_client/error.rb

@@ -0,0 +1,87 @@
+
+class AirtableClient
+  # Raised for every Airtable API error. Carries the Airtable error type and
+  # the HTTP status, so callers can branch on the failure mode.
+  #
+  # Note that HTTP 429 and 503 are retried automatically (up to 3 attempts)
+  # before this is raised.
+  #
+  # @example
+  #   begin
+  #     table.find('recMissing')
+  #   rescue AirtableClient::Error => e
+  #     e.type         # => "NOT_FOUND"
+  #     e.status_code  # => 404
+  #   end
+  class Error < StandardError
+
+    # @return [String, nil] human-readable message from the API
+    attr_reader :message
+
+    # @return [String, nil] Airtable's error type when the response includes
+    #   one (e.g. +"UNKNOWN_COLUMN_NAME"+), otherwise classified from the
+    #   status code via {STATUS_CODE_ERROR_TYPES}
+    attr_reader :type
+
+    # @return [Integer, nil] the HTTP status code
+    attr_reader :status_code
+
+    # Maps HTTP status codes to named error types, matching the official airtable.js error handler.
+    # Used as a fallback when the response body doesn't include a type.
+    STATUS_CODE_ERROR_TYPES = {
+      401 => 'AUTHENTICATION_REQUIRED',
+      403 => 'NOT_AUTHORIZED',
+      404 => 'NOT_FOUND',
+      422 => 'INVALID_REQUEST',
+      429 => 'TOO_MANY_REQUESTS',
+      500 => 'SERVER_ERROR',
+      503 => 'SERVICE_UNAVAILABLE'
+    }.freeze
+
+    # @param error_hash [Hash] the API's error object,
+    #   e.g. +{"type" => "UNKNOWN_COLUMN_NAME", "message" => "..."}+
+    # @param status_code [Integer, nil] the HTTP status code
+    def initialize(error_hash, status_code: nil)
+      @message = error_hash['message']
+      @type = error_hash['type']
+      @status_code = status_code
+      super(@message)
+    end
+
+    # Builds an Error from a raw HTTP status code and response body.
+    # Attempts JSON parse first; falls back to classifying by status code.
+    # The type from the JSON body takes precedence over the status code
+    # mapping, because Airtable returns specific types (e.g.
+    # UNKNOWN_COLUMN_NAME) that are more informative.
+    #
+    # @param status_code [Integer]
+    # @param body [String, nil] the raw response body
+    # @return [Error]
+    def self.from_response(status_code, body)
+      error_hash = parse_error_body(body)
+      error_hash['type'] ||= STATUS_CODE_ERROR_TYPES.fetch(status_code, 'UNKNOWN_ERROR')
+      error_hash['message'] ||= default_message_for(status_code, body)
+      new(error_hash, status_code: status_code)
+    end
+
+    class << self
+      private
+
+      def parse_error_body(body)
+        return {} if body.nil? || body.to_s.strip.empty?
+
+        parsed = JSON.parse(body)
+        parsed.is_a?(Hash) && parsed['error'].is_a?(Hash) ? parsed['error'] : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def default_message_for(status_code, body)
+        type = STATUS_CODE_ERROR_TYPES.fetch(status_code, 'UNKNOWN_ERROR')
+        truncated = body.to_s[0..200]
+        "#{type} (HTTP #{status_code}): #{truncated}"
+      end
+    end
+
+  end
+end

data/lib/airtable_client/rate_limiter.rb

@@ -0,0 +1,110 @@
+class AirtableClient
+  # Thread-safe sliding window rate limiter.
+  #
+  # Airtable enforces a limit of 5 requests per second per base. This limiter
+  # delays requests that would exceed the limit, preventing 429 responses.
+  #
+  # The limiter is process-global (singleton) and keyed by base ID (app_token),
+  # so all Table instances in the same Sidekiq process share it.
+  #
+  # Usage is automatic — Table calls RateLimiter.wait! before each request.
+  class RateLimiter
+    DEFAULT_MAX_REQUESTS = 5
+    DEFAULT_WINDOW_SECONDS = 1.0
+
+    def initialize(max_requests: DEFAULT_MAX_REQUESTS, window_seconds: DEFAULT_WINDOW_SECONDS, clock: nil)
+      @max_requests = max_requests
+      @window_seconds = window_seconds
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @buckets = {}
+      @buckets_mutex = Mutex.new
+    end
+
+    # Blocks until a request slot is available for the given base.
+    #
+    # @param base_id [String] the base id the request targets
+    # @return [void]
+    def wait!(base_id)
+      bucket = bucket_for(base_id)
+      bucket.wait!
+    end
+
+    class << self
+      def instance
+        @instance_mutex.synchronize do
+          @instance ||= new
+        end
+      end
+
+      def instance=(limiter)
+        @instance_mutex.synchronize do
+          @instance = limiter
+        end
+      end
+
+      def reset!
+        @instance_mutex.synchronize do
+          @instance = nil
+        end
+      end
+    end
+
+    @instance_mutex = Mutex.new
+    @instance = nil
+
+    private
+
+    # Note: buckets are created per base_id and never evicted. For typical
+    # usage (a handful of bases), this is fine. If the process touches
+    # thousands of distinct bases over its lifetime, consider adding LRU
+    # eviction or periodic cleanup.
+    def bucket_for(base_id)
+      @buckets_mutex.synchronize do
+        @buckets[base_id] ||= Bucket.new(@max_requests, @window_seconds, @clock)
+      end
+    end
+
+    # Per-base sliding window bucket. Tracks timestamps of recent requests
+    # and sleeps when the window is full.
+    #
+    # Thread-safety: the mutex is released during sleep so other threads
+    # targeting the same base can proceed once a slot opens.
+    class Bucket
+      def initialize(max_requests, window_seconds, clock)
+        @max_requests = max_requests
+        @window_seconds = window_seconds
+        @clock = clock
+        @timestamps = []
+        @mutex = Mutex.new
+      end
+
+      def wait!
+        loop do
+          sleep_time = nil
+
+          @mutex.synchronize do
+            now = @clock.call
+            evict_expired!(now)
+
+            if @timestamps.length >= @max_requests
+              sleep_time = @window_seconds - (now - @timestamps.first)
+              sleep_time = 0.001 if sleep_time <= 0
+            else
+              @timestamps << now
+              return
+            end
+          end
+
+          # Sleep WITHOUT holding the mutex so other threads aren't blocked
+          Kernel.sleep(sleep_time)
+        end
+      end
+
+      private
+
+      def evict_expired!(now)
+        @timestamps.reject! { |t| now - t >= @window_seconds }
+      end
+    end
+  end
+end