attio-rails 0.1.1 → 0.2.0

data/CONCEPTS.md

@@ -0,0 +1,448 @@
+# Attio Rails - Concepts & Architecture
+
+## Table of Contents
+- [Core Concepts](#core-concepts)
+- [Architecture Overview](#architecture-overview)
+- [Sync Flow](#sync-flow)
+- [Batch Processing](#batch-processing)
+- [Error Handling & Retry Strategy](#error-handling--retry-strategy)
+- [Testing Strategy](#testing-strategy)
+
+## Core Concepts
+
+### 1. ActiveRecord Integration Pattern
+
+The gem uses the **Concern pattern** to mix functionality into ActiveRecord models. This provides a clean, Rails-idiomatic interface:
+
+```mermaid
+graph TD
+    A[ActiveRecord Model] -->|includes| B[Attio::Rails::Concerns::Syncable]
+    B -->|provides| C[Sync Methods]
+    B -->|provides| D[Callbacks]
+    B -->|provides| E[Attribute Mapping]
+    
+    C --> F[sync_to_attio_now]
+    C --> G[sync_to_attio_later]
+    C --> H[remove_from_attio]
+    
+    D --> I[before_attio_sync]
+    D --> J[after_attio_sync]
+    D --> K[ActiveRecord Callbacks]
+```
+
+### 2. Attribute Mapping System
+
+The attribute mapping system supports multiple mapping strategies:
+
+```mermaid
+graph LR
+    A[Model Attributes] --> B{Mapping Type}
+    B -->|Symbol| C[Method Call]
+    B -->|String| D[Method Call]
+    B -->|Proc/Lambda| E[Dynamic Evaluation]
+    B -->|Static Value| F[Direct Value]
+    
+    C --> G[Attio Attributes]
+    D --> G
+    E --> G
+    F --> G
+```
+
+**Example mappings:**
+```ruby
+{
+  email: :email_address,           # Symbol -> calls model.email_address
+  name: "full_name",               # String -> calls model.full_name
+  type: "customer",                # Static -> always "customer"
+  count: ->(m) { m.items.count }  # Lambda -> evaluated dynamically
+}
+```
+
+## Architecture Overview
+
+### System Components
+
+```mermaid
+graph TB
+    subgraph "Rails Application"
+        A[ActiveRecord Model]
+        B[ActiveJob Queue]
+    end
+    
+    subgraph "Attio Rails Gem"
+        C[Syncable Concern]
+        D[AttioSyncJob]
+        E[BatchSync]
+        F[Configuration]
+    end
+    
+    subgraph "External"
+        G[Attio API]
+    end
+    
+    A -->|includes| C
+    C -->|enqueues| D
+    C -->|uses| E
+    D -->|processes| B
+    E -->|bulk operations| G
+    D -->|sync/delete| G
+    C -->|immediate sync| G
+    F -->|configures| C
+    F -->|configures| D
+```
+
+## Sync Flow
+
+### Automatic Sync Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Model
+    participant Syncable
+    participant AttioSyncJob
+    participant AttioAPI
+    
+    User->>Model: create/update/destroy
+    Model->>Syncable: after_commit callback
+    
+    alt Sync Enabled & Conditions Met
+        alt Background Sync
+            Syncable->>AttioSyncJob: enqueue job
+            AttioSyncJob-->>AttioSyncJob: process async
+            AttioSyncJob->>AttioAPI: sync data
+            AttioAPI-->>AttioSyncJob: response
+            AttioSyncJob->>Model: update attio_record_id
+        else Immediate Sync
+            Syncable->>AttioAPI: sync data
+            AttioAPI-->>Syncable: response
+            Syncable->>Model: update attio_record_id
+        end
+    else Sync Disabled or Conditions Not Met
+        Syncable-->>Model: skip sync
+    end
+```
+
+### Manual Sync Options
+
+```mermaid
+graph TD
+    A[Manual Sync Trigger] --> B{Sync Method}
+    
+    B -->|sync_to_attio_now| C[Immediate Sync]
+    B -->|sync_to_attio_later| D[Background Job]
+    B -->|sync_to_attio| E{Config Check}
+    
+    E -->|background_sync=true| D
+    E -->|background_sync=false| C
+    
+    C --> F[Direct API Call]
+    D --> G[Enqueue AttioSyncJob]
+    
+    F --> H[Attio API]
+    G --> I[Job Queue]
+    I --> H
+```
+
+## Batch Processing
+
+### BatchSync Flow
+
+```mermaid
+flowchart TD
+    A[BatchSync.perform] --> B[Initialize Results Hash]
+    B --> C[Process in Batches]
+    
+    C --> D{Async Mode?}
+    
+    D -->|Yes| E[Enqueue Batch]
+    D -->|No| F[Sync Batch]
+    
+    E --> G[For Each Record]
+    G --> H[Enqueue AttioSyncJob]
+    
+    F --> I[For Each Record]
+    I --> J{Has attio_record_id?}
+    
+    J -->|Yes| K[Update Record]
+    J -->|No| L[Create Record]
+    
+    K --> M[API Call]
+    L --> M
+    
+    M --> N{Success?}
+    N -->|Yes| O[Add to success array]
+    N -->|No| P[Add to failed array]
+    
+    H --> Q[Add to success array]
+    
+    O --> R[Return Results]
+    P --> R
+    Q --> R
+```
+
+### Batch Processing Strategies
+
+```mermaid
+graph LR
+    A[Large Dataset] --> B[find_in_batches]
+    B --> C[Batch 1]
+    B --> D[Batch 2]
+    B --> E[Batch N]
+    
+    C --> F{Processing Mode}
+    D --> F
+    E --> F
+    
+    F -->|Async| G[Job Queue]
+    F -->|Sync| H[Direct Processing]
+    
+    G --> I[Parallel Processing]
+    H --> J[Sequential Processing]
+```
+
+## Error Handling & Retry Strategy
+
+### Error Flow
+
+```mermaid
+flowchart TD
+    A[Sync Operation] --> B{Success?}
+    
+    B -->|Yes| C[Update Local Record]
+    B -->|No| D[Error Occurred]
+    
+    D --> E{Has Error Handler?}
+    
+    E -->|Yes| F[Call Error Handler]
+    E -->|No| G{Environment?}
+    
+    F --> H[Custom Logic]
+    
+    G -->|Development| I[Raise Error]
+    G -->|Production| J[Log Error]
+    
+    H --> K{In Background Job?}
+    K -->|Yes| L[Retry Logic]
+    K -->|No| M[Complete]
+    
+    L --> N{Retry Attempts < 3?}
+    N -->|Yes| O[Wait & Retry]
+    N -->|No| P[Dead Letter Queue]
+    
+    O --> A
+```
+
+### Retry Strategy with ActiveJob
+
+```mermaid
+graph TD
+    A[Job Fails] --> B[Retry Mechanism]
+    B --> C{Attempt 1}
+    C -->|Fails| D[Wait 3 seconds]
+    D --> E{Attempt 2}
+    E -->|Fails| F[Wait 18 seconds]
+    F --> G{Attempt 3}
+    G -->|Fails| H[Job Failed]
+    G -->|Success| I[Complete]
+    E -->|Success| I
+    C -->|Success| I
+    
+    style H fill:#f96
+    style I fill:#9f6
+```
+
+## Testing Strategy
+
+### Test Double Architecture
+
+```mermaid
+graph TD
+    A[RSpec Test] --> B[Test Helpers]
+    
+    B --> C[stub_attio_client]
+    C --> D[Mock Client]
+    C --> E[Mock Records API]
+    
+    B --> F[expect_attio_sync]
+    F --> G[Expectation Setup]
+    
+    B --> H[with_attio_sync_disabled]
+    H --> I[Temporary Config Change]
+    
+    D --> J[No Real API Calls]
+    E --> J
+    
+    J --> K[Fast Tests]
+    J --> L[Predictable Results]
+```
+
+### Testing Layers
+
+```mermaid
+graph TB
+    subgraph "Unit Tests"
+        A[Model Tests]
+        B[Concern Tests]
+        C[Job Tests]
+    end
+    
+    subgraph "Integration Tests"
+        D[Sync Flow Tests]
+        E[Batch Processing Tests]
+    end
+    
+    subgraph "Test Helpers"
+        F[Stubbed Client]
+        G[Job Assertions]
+        H[Config Helpers]
+    end
+    
+    A --> F
+    B --> F
+    C --> G
+    D --> F
+    D --> G
+    E --> F
+    E --> H
+```
+
+## Configuration Cascade
+
+### Configuration Priority
+
+```mermaid
+graph TD
+    A[Configuration Sources] --> B[Environment Variables]
+    A --> C[Initializer Config]
+    A --> D[Model-level Options]
+    A --> E[Method-level Options]
+    
+    B --> F{Priority}
+    C --> F
+    D --> F
+    E --> F
+    
+    F --> G[Final Configuration]
+    
+    style E fill:#9f6
+    style D fill:#af9
+    style C fill:#cf9
+    style B fill:#ff9
+```
+
+Priority order (highest to lowest):
+1. Method-level options (e.g., `sync_to_attio_now(force: true)`)
+2. Model-level options (e.g., `syncs_with_attio 'people', if: :active?`)
+3. Initializer configuration (e.g., `config.background_sync = true`)
+4. Environment variables (e.g., `ATTIO_API_KEY`)
+
+## Data Flow Transformations
+
+### Transform Pipeline
+
+```mermaid
+graph LR
+    A[Raw Model Data] --> B[Attribute Mapping]
+    B --> C[Transform Function]
+    C --> D[Validated Data]
+    D --> E[API Payload]
+    
+    B -.->|Example| B1[email: :work_email]
+    C -.->|Example| C1[Add computed fields]
+    D -.->|Example| D1[Remove nil values]
+    E -.->|Example| E1[JSON structure]
+```
+
+### Callback Chain
+
+```mermaid
+sequenceDiagram
+    participant Model
+    participant Callbacks
+    participant Sync
+    participant API
+    
+    Model->>Callbacks: before_attio_sync
+    Callbacks->>Callbacks: prepare_data
+    Callbacks->>Sync: proceed with sync
+    Sync->>Sync: transform_attributes
+    Sync->>API: send data
+    API-->>Sync: response
+    Sync->>Callbacks: after_attio_sync
+    Callbacks->>Callbacks: log_sync
+    Callbacks->>Model: complete
+```
+
+## Performance Considerations
+
+### Optimization Strategies
+
+```mermaid
+graph TD
+    A[Performance Optimizations] --> B[Batch Processing]
+    A --> C[Background Jobs]
+    A --> D[Connection Pooling]
+    A --> E[Smart Retries]
+    
+    B --> F[Reduce API Calls]
+    C --> G[Non-blocking Operations]
+    D --> H[Reuse Connections]
+    E --> I[Exponential Backoff]
+    
+    F --> J[Better Performance]
+    G --> J
+    H --> J
+    I --> J
+```
+
+### Load Distribution
+
+```mermaid
+graph LR
+    A[100 Records to Sync] --> B[BatchSync]
+    B --> C[Batch 1: Records 1-25]
+    B --> D[Batch 2: Records 26-50]
+    B --> E[Batch 3: Records 51-75]
+    B --> F[Batch 4: Records 76-100]
+    
+    C --> G[Job Queue]
+    D --> G
+    E --> G
+    F --> G
+    
+    G --> H[Worker 1]
+    G --> I[Worker 2]
+    G --> J[Worker N]
+    
+    style G fill:#9cf
+```
+
+## Best Practices
+
+### Recommended Patterns
+
+1. **Use Background Sync for Production**
+   - Prevents blocking web requests
+   - Provides automatic retry on failure
+   - Better user experience
+
+2. **Implement Error Handlers**
+   - Log errors to monitoring services
+   - Gracefully handle API downtime
+   - Notify administrators of issues
+
+3. **Optimize Attribute Mapping**
+   - Only sync necessary fields
+   - Use transforms to reduce payload size
+   - Cache computed values when possible
+
+4. **Test Thoroughly**
+   - Use provided test helpers
+   - Mock external API calls
+   - Test error scenarios
+
+5. **Monitor Performance**
+   - Track sync success rates
+   - Monitor job queue depth
+   - Alert on repeated failures

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 # Specify your gem's dependencies in attio-rails.gemspec
@@ -6,15 +8,19 @@ gemspec
 gem "rake", "~> 13.0"
 
 group :development, :test do
-  gem "rspec", "~> 3.12"
-  gem "rspec-rails", "~> 6.0"
+  gem "bundler-audit", "~> 0.9"
+  gem "danger", "~> 9.4"
+  gem "pry", "~> 0.14"
   gem "rails", "~> 7.0"
-  gem "sqlite3", "~> 1.4"
-  gem "simplecov", "~> 0.22"
-  gem "simplecov-console", "~> 0.9"
+  gem "redcarpet", "~> 3.5"
+  gem "rspec", "~> 3.13"
+  gem "rspec-rails", "~> 6.0"
   gem "rubocop", "~> 1.50"
   gem "rubocop-rails", "~> 2.19"
-  gem "rubocop-rspec", "~> 2.19"
-  gem "pry", "~> 0.14"
-  gem "webmock", "~> 3.18"
+  gem "rubocop-rspec", "~> 3.6"
+  gem "simplecov", "~> 0.22"
+  gem "simplecov-console", "~> 0.9"
+  gem "sqlite3", "~> 1.4"
+  gem "webmock", "~> 3.19"
+  gem "yard", "~> 0.9"
 end

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rubocop/rake_task"
@@ -7,9 +9,9 @@ RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
 YARD::Rake::YardocTask.new do |t|
-  t.files   = ['lib/**/*.rb']
-  t.options = ['--markup-provider=redcarpet', '--markup=markdown', '--protected', '--private']
-  t.stats_options = ['--list-undoc']
+  t.files   = ["lib/**/*.rb"]
+  t.options = ["--markup-provider=redcarpet", "--markup=markdown", "--protected", "--private"]
+  t.stats_options = ["--list-undoc"]
 end
 
 namespace :yard do
@@ -17,13 +19,13 @@ namespace :yard do
   task :server do
     sh "bundle exec yard server --reload"
   end
-  
+
   desc "Generate documentation for GitHub Pages"
   task :gh_pages do
     sh "bundle exec yard --output-dir docs"
     # Create .nojekyll file for GitHub Pages
-    File.open("docs/.nojekyll", "w") {}
+    File.write("docs/.nojekyll", "")
   end
 end
 
-task :default => [:spec, :rubocop]
+task default: %i[spec rubocop]

data/attio-rails.gemspec

@@ -1,4 +1,6 @@
-require_relative 'lib/attio/rails/version'
+# frozen_string_literal: true
+
+require_relative "lib/attio/rails/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "attio-rails"
@@ -6,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Ernest Sim"]
   spec.email         = ["ernest.codes@gmail.com"]
 
-  spec.summary       = %q{Rails integration for the Attio API client}
-  spec.description   = %q{Rails-specific features and integrations for the Attio Ruby client, including model concerns and generators}
+  spec.summary       = "Rails integration for the Attio API client"
+  spec.description   = "Rails-specific features and integrations for the Attio Ruby client, including model concerns and generators"
   spec.homepage      = "https://github.com/idl3/attio-rails"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
@@ -21,26 +23,13 @@ Gem::Specification.new do |spec|
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "attio", "~> 0.1", ">= 0.1.1"
+  spec.add_dependency "attio", "~> 0.1", ">= 0.1.3"
   spec.add_dependency "rails", ">= 6.1", "< 9.0"
-
-  spec.add_development_dependency "yard", "~> 0.9"
-  spec.add_development_dependency "redcarpet", "~> 3.5"
-  spec.add_development_dependency "rspec", "~> 3.13"
-  spec.add_development_dependency "rubocop", "~> 1.50"
-  spec.add_development_dependency "simplecov", "~> 0.22"
-  spec.add_development_dependency "simplecov-console", "~> 0.9"
-  spec.add_development_dependency "webmock", "~> 3.19"
-  spec.add_development_dependency "pry", "~> 0.14"
-  spec.add_development_dependency "sqlite3", "~> 1.4"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "bundler-audit", "~> 0.9"
-  spec.add_development_dependency "danger", "~> 9.4"
 end

data/lib/attio/rails/concerns/syncable.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Attio
   module Rails
     module Concerns
@@ -5,7 +7,7 @@ module Attio
         extend ActiveSupport::Concern
 
         included do
-          after_commit :sync_to_attio, on: [:create, :update], if: :should_sync_to_attio?
+          after_commit :sync_to_attio, on: %i[create update], if: :should_sync_to_attio?
           after_commit :remove_from_attio, on: :destroy, if: :should_remove_from_attio?
 
           class_attribute :attio_object_type
@@ -18,7 +20,7 @@ module Attio
           def syncs_with_attio(object_type, mapping = {}, options = {})
             self.attio_object_type = object_type
             self.attio_attribute_mapping = mapping
-            self.attio_sync_conditions = options[:if] || -> { true }
+            self.attio_sync_conditions = options[:if]
             self.attio_identifier_attribute = options[:identifier] || :id
           end
 
@@ -46,7 +48,7 @@ module Attio
         def sync_to_attio_now
           client = Attio::Rails.client
           attributes = attio_attributes
-          
+
           if attio_record_id.present?
             client.records.update(
               object: attio_object_type,
@@ -58,7 +60,7 @@ module Attio
               object: attio_object_type,
               data: { values: attributes }
             )
-            update_column(:attio_record_id, response['data']['id']) if respond_to?(:attio_record_id=)
+            update_column(:attio_record_id, response["data"]["id"]) if respond_to?(:attio_record_id=)
           end
         end
 
@@ -80,7 +82,7 @@ module Attio
 
         def remove_from_attio_now
           return unless attio_record_id.present?
-          
+
           client = Attio::Rails.client
           client.records.delete(
             object: attio_object_type,
@@ -92,23 +94,19 @@ module Attio
           return {} unless attio_attribute_mapping
 
           attio_attribute_mapping.each_with_object({}) do |(attio_key, local_key), hash|
-            value = case local_key
-                    when Proc
-                      local_key.call(self)
-                    when Symbol, String
-                      send(local_key)
-                    else
-                      local_key
-                    end
+            value = attribute_value_for(local_key)
             hash[attio_key] = value unless value.nil?
           end
         end
 
         def should_sync_to_attio?
           return false unless Attio::Rails.sync_enabled?
-          return false unless attio_object_type.present? && attio_attribute_mapping.present?
-          
+          return false unless attio_object_type.present?
+          return false unless attio_attribute_mapping.present?
+
           condition = attio_sync_conditions
+          return true if condition.nil?
+
           case condition
           when Proc
             instance_exec(&condition)
@@ -126,7 +124,20 @@ module Attio
         def attio_identifier
           send(attio_identifier_attribute)
         end
+
+        private def attribute_value_for(local_key)
+          case local_key
+          when Proc
+            local_key.call(self)
+          when Symbol
+            send(local_key)
+          when String
+            respond_to?(local_key) ? send(local_key) : local_key
+          else
+            local_key
+          end
+        end
       end
     end
   end
-end
+end

data/lib/attio/rails/configuration.rb

@@ -1,12 +1,18 @@
+# frozen_string_literal: true
+
 module Attio
   module Rails
     class Configuration
       attr_accessor :api_key, :default_workspace_id, :logger, :sync_enabled, :background_sync
 
       def initialize
-        @api_key = ENV['ATTIO_API_KEY']
+        @api_key = ENV.fetch("ATTIO_API_KEY", nil)
         @default_workspace_id = nil
-        @logger = defined?(::Rails) ? ::Rails.logger : Logger.new(STDOUT)
+        @logger = if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+                    ::Rails.logger
+                  else
+                    ::Logger.new($stdout)
+                  end
         @sync_enabled = true
         @background_sync = true
       end
@@ -30,6 +36,7 @@ module Attio
 
       def client
         raise ConfigurationError, "Attio API key not configured" unless configuration.valid?
+
         @client ||= ::Attio.client(api_key: configuration.api_key)
       end
 
@@ -52,4 +59,4 @@ module Attio
 
     class ConfigurationError < StandardError; end
   end
-end
+end