attio-rails 0.1.0

data/Gemfile

@@ -0,0 +1,20 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in attio-rails.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+group :development, :test do
+  gem "rspec", "~> 3.12"
+  gem "rspec-rails", "~> 6.0"
+  gem "rails", "~> 7.0"
+  gem "sqlite3", "~> 1.4"
+  gem "simplecov", "~> 0.22"
+  gem "simplecov-console", "~> 0.9"
+  gem "rubocop", "~> 1.50"
+  gem "rubocop-rails", "~> 2.19"
+  gem "rubocop-rspec", "~> 2.19"
+  gem "pry", "~> 0.14"
+  gem "webmock", "~> 3.18"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Ernest Sim
+
+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,243 @@
+# Attio Rails
+
+[![Documentation](https://img.shields.io/badge/docs-yard-blue.svg)](https://idl3.github.io/attio-rails)
+[![Gem Version](https://badge.fury.io/rb/attio-rails.svg)](https://badge.fury.io/rb/attio-rails)
+[![CI](https://github.com/idl3/attio-rails/actions/workflows/ci.yml/badge.svg)](https://github.com/idl3/attio-rails/actions/workflows/ci.yml)
+
+Rails integration for the [Attio](https://github.com/idl3/attio) Ruby client. This gem provides Rails-specific features including ActiveRecord model synchronization, generators, and background job integration.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'attio-rails', '~> 0.1.0'
+```
+
+And then execute:
+
+```bash
+bundle install
+rails generate attio:install
+```
+
+## Configuration
+
+After running the install generator, configure Attio in `config/initializers/attio.rb`:
+
+```ruby
+Attio::Rails.configure do |config|
+  config.api_key = ENV['ATTIO_API_KEY']
+  config.async = true  # Use ActiveJob for syncing
+  config.queue = :default  # ActiveJob queue name
+  config.logger = Rails.logger
+end
+```
+
+## Usage
+
+### ActiveRecord Integration
+
+Add the `Attio::Rails::Syncable` concern to your models:
+
+```ruby
+class User < ApplicationRecord
+  include Attio::Rails::Syncable
+  
+  attio_syncable object: 'people',
+                 attributes: [:email, :first_name, :last_name],
+                 identifier: :email
+  
+  # Optional callbacks
+  before_attio_sync :prepare_data
+  after_attio_sync :log_sync
+  
+  private
+  
+  def prepare_data
+    # Prepare data before syncing
+  end
+  
+  def log_sync(response)
+    Rails.logger.info "Synced to Attio: #{response['id']}"
+  end
+end
+```
+
+### Manual Syncing
+
+```ruby
+# Sync a single record
+user = User.find(1)
+user.sync_to_attio
+
+# Sync multiple records
+User.where(active: true).find_each(&:sync_to_attio)
+
+# Async sync (requires ActiveJob)
+user.sync_to_attio_later
+```
+
+### Custom Field Mapping
+
+```ruby
+class Company < ApplicationRecord
+  include Attio::Rails::Syncable
+  
+  attio_syncable object: 'companies',
+                 attributes: {
+                   name: :company_name,
+                   domain: :website_url,
+                   employee_count: ->(c) { c.employees.count }
+                 },
+                 identifier: :domain
+end
+```
+
+### Batch Operations
+
+```ruby
+# Sync multiple records efficiently
+Attio::Rails::BatchSync.perform(
+  User.where(updated_at: 1.day.ago..),
+  object: 'people'
+)
+```
+
+### ActiveJob Integration
+
+The gem automatically uses ActiveJob for background syncing when configured:
+
+```ruby
+class User < ApplicationRecord
+  include Attio::Rails::Syncable
+  
+  attio_syncable object: 'people', async: true
+  
+  # Automatically syncs in background after save
+  after_commit :sync_to_attio_later
+end
+```
+
+### Generator
+
+The install generator creates:
+- Configuration initializer at `config/initializers/attio.rb`
+- ActiveJob class at `app/jobs/attio_sync_job.rb`
+- Migration for tracking sync status (optional)
+
+```bash
+rails generate attio:install
+rails generate attio:install --skip-job  # Skip job creation
+rails generate attio:install --skip-migration  # Skip migration
+```
+
+## Advanced Features
+
+### Conditional Syncing
+
+```ruby
+class User < ApplicationRecord
+  include Attio::Rails::Syncable
+  
+  attio_syncable object: 'people',
+                 if: :should_sync_to_attio?
+  
+  def should_sync_to_attio?
+    confirmed? && !deleted?
+  end
+end
+```
+
+### Error Handling
+
+```ruby
+class User < ApplicationRecord
+  include Attio::Rails::Syncable
+  
+  attio_syncable object: 'people',
+                 on_error: :handle_sync_error
+  
+  def handle_sync_error(error)
+    Rails.logger.error "Attio sync failed: #{error.message}"
+    Sentry.capture_exception(error)
+  end
+end
+```
+
+### Custom Transformations
+
+```ruby
+class User < ApplicationRecord
+  include Attio::Rails::Syncable
+  
+  attio_syncable object: 'people',
+                 transform: :transform_for_attio
+  
+  def transform_for_attio(attributes)
+    attributes.merge(
+      full_name: "#{first_name} #{last_name}",
+      tags: user_tags.pluck(:name)
+    )
+  end
+end
+```
+
+## Testing
+
+The gem includes RSpec helpers for testing:
+
+```ruby
+# In spec/rails_helper.rb
+require 'attio/rails/rspec'
+
+# In your specs
+RSpec.describe User do
+  include Attio::Rails::RSpec::Helpers
+  
+  it 'syncs to Attio' do
+    user = create(:user)
+    
+    expect_attio_sync(object: 'people') do
+      user.sync_to_attio
+    end
+  end
+end
+```
+
+## Development
+
+After checking out the repo:
+
+```bash
+bundle install
+cd spec/dummy
+rails db:create db:migrate
+cd ../..
+bundle exec rspec
+```
+
+To run tests against different Rails versions:
+
+```bash
+RAILS_VERSION=7.1 bundle update
+bundle exec rspec
+
+RAILS_VERSION=7.0 bundle update
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/idl3/attio-rails. Please read our [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Support
+
+- 📖 [Documentation](https://idl3.github.io/attio-rails)
+- 🐛 [Issues](https://github.com/idl3/attio-rails/issues)
+- 💬 [Discussions](https://github.com/idl3/attio-rails/discussions)
+- 📦 [Main Attio Gem](https://github.com/idl3/attio)

data/Rakefile

@@ -0,0 +1,29 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+require "yard"
+
+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']
+end
+
+namespace :yard do
+  desc "Generate documentation and serve it with live reloading"
+  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") {}
+  end
+end
+
+task :default => [:spec, :rubocop]

data/SECURITY.md

@@ -0,0 +1,63 @@
+# Security Policy
+
+## Supported Versions
+
+We release patches for security vulnerabilities. Which versions are eligible depends on the CVSS v3.0 Rating:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability within this project, please follow these steps:
+
+1. **Do NOT** create a public GitHub issue
+2. Send details to the maintainers through GitHub Security Advisories
+3. Include the following in your report:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Possible impact
+   - Suggested fix (if any)
+
+### What to expect
+
+- Acknowledgment of your report within 48 hours
+- Regular updates on our progress
+- Credit for responsible disclosure (unless you prefer to remain anonymous)
+
+## Security Best Practices
+
+When using this gem:
+
+1. **API Key Management**
+   - Never commit API keys to version control
+   - Use Rails credentials or environment variables
+   - Rotate API keys regularly
+   - Use different keys for different environments
+
+2. **Rails Security**
+   - Keep Rails and dependencies updated
+   - Follow Rails security best practices
+   - Use strong parameters
+   - Implement proper authentication and authorization
+
+3. **Data Handling**
+   - Be cautious with sensitive data in logs
+   - Use Rails encrypted credentials
+   - Implement proper error handling
+   - Sanitize user input before syncing to Attio
+
+## Security Features
+
+This gem includes:
+- Integration with Rails security features
+- Automatic API key masking in logs
+- SSL/TLS verification by default
+- Input validation and sanitization
+- Safe handling of ActiveRecord callbacks
+
+## Contact
+
+For security concerns, please use GitHub Security Advisories or contact the maintainers directly through GitHub.

data/attio-rails.gemspec

@@ -0,0 +1,42 @@
+require_relative 'lib/attio/rails/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "attio-rails"
+  spec.version       = Attio::Rails::VERSION
+  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.homepage      = "https://github.com/idl3/attio-rails"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://idl3.github.io/attio-rails"
+
+  # 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
+    `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 "rails", ">= 6.1", "< 8.0"
+
+  spec.add_development_dependency "yard", "~> 0.9"
+  spec.add_development_dependency "redcarpet", "~> 3.5"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "bundler-audit", "~> 0.9"
+  spec.add_development_dependency "danger", "~> 9.4"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "attio/rails"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/docs/index.html

@@ -0,0 +1,91 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Attio Rails Integration Documentation</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            line-height: 1.6;
+            color: #333;
+            max-width: 800px;
+            margin: 0 auto;
+            padding: 20px;
+            background: #f8f9fa;
+        }
+        .container {
+            background: white;
+            padding: 40px;
+            border-radius: 8px;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+        }
+        h1 {
+            color: #2c3e50;
+            border-bottom: 2px solid #3498db;
+            padding-bottom: 10px;
+        }
+        .notice {
+            background: #e3f2fd;
+            border-left: 4px solid #2196f3;
+            padding: 15px;
+            margin: 20px 0;
+            border-radius: 4px;
+        }
+        .button {
+            display: inline-block;
+            background: #3498db;
+            color: white;
+            padding: 10px 20px;
+            text-decoration: none;
+            border-radius: 4px;
+            margin: 10px 10px 10px 0;
+            transition: background 0.3s;
+        }
+        .button:hover {
+            background: #2980b9;
+        }
+        pre {
+            background: #f4f4f4;
+            border: 1px solid #ddd;
+            border-radius: 4px;
+            padding: 15px;
+            overflow-x: auto;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>Attio Rails Integration Documentation</h1>
+        
+        <div class="notice">
+            <strong>Documentation Status:</strong> This is a placeholder page. The full API documentation will be generated automatically when the gem is built.
+        </div>
+        
+        <h2>Quick Start</h2>
+        <p>Add the gem to your Gemfile:</p>
+        <pre><code>gem 'attio-rails'</code></pre>
+        
+        <p>Run the installer:</p>
+        <pre><code>rails generate attio:install</code></pre>
+        
+        <h2>Documentation Links</h2>
+        <a href="./file.README.html" class="button">README</a>
+        <a href="./Attio/Rails.html" class="button">API Documentation</a>
+        <a href="./method_list.html" class="button">Method List</a>
+        <a href="./class_list.html" class="button">Class List</a>
+        
+        <h2>GitHub Repository</h2>
+        <p>Visit the <a href="https://github.com/your-username/attio-rails">GitHub repository</a> for source code, issues, and contributions.</p>
+        
+        <h2>Generate Documentation Locally</h2>
+        <p>To generate the full documentation locally:</p>
+        <pre><code>bundle exec rake yard
+bundle exec yard server</code></pre>
+        
+        <div class="notice">
+            <strong>Note:</strong> This documentation is automatically updated when changes are pushed to the main branch.
+        </div>
+    </div>
+</body>
+</html>

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

@@ -0,0 +1,132 @@
+module Attio
+  module Rails
+    module Concerns
+      module Syncable
+        extend ActiveSupport::Concern
+
+        included do
+          after_commit :sync_to_attio, on: [:create, :update], if: :should_sync_to_attio?
+          after_commit :remove_from_attio, on: :destroy, if: :should_remove_from_attio?
+
+          class_attribute :attio_object_type
+          class_attribute :attio_attribute_mapping
+          class_attribute :attio_sync_conditions
+          class_attribute :attio_identifier_attribute
+        end
+
+        class_methods do
+          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_identifier_attribute = options[:identifier] || :id
+          end
+
+          def skip_attio_sync
+            skip_callback :commit, :after, :sync_to_attio
+            skip_callback :commit, :after, :remove_from_attio
+          end
+        end
+
+        def sync_to_attio
+          if Attio::Rails.background_sync?
+            AttioSyncJob.perform_later(
+              model_name: self.class.name,
+              model_id: id,
+              action: :sync
+            )
+          else
+            sync_to_attio_now
+          end
+        rescue StandardError => e
+          Attio::Rails.logger.error "Failed to sync to Attio: #{e.message}"
+          raise if ::Rails.env.development?
+        end
+
+        def sync_to_attio_now
+          client = Attio::Rails.client
+          attributes = attio_attributes
+          
+          if attio_record_id.present?
+            client.records.update(
+              object: attio_object_type,
+              id: attio_record_id,
+              data: { values: attributes }
+            )
+          else
+            response = client.records.create(
+              object: attio_object_type,
+              data: { values: attributes }
+            )
+            update_column(:attio_record_id, response['data']['id']) if respond_to?(:attio_record_id=)
+          end
+        end
+
+        def remove_from_attio
+          if Attio::Rails.background_sync?
+            AttioSyncJob.perform_later(
+              model_name: self.class.name,
+              model_id: id,
+              action: :delete,
+              attio_record_id: attio_record_id
+            )
+          else
+            remove_from_attio_now
+          end
+        rescue StandardError => e
+          Attio::Rails.logger.error "Failed to remove from Attio: #{e.message}"
+          raise if ::Rails.env.development?
+        end
+
+        def remove_from_attio_now
+          return unless attio_record_id.present?
+          
+          client = Attio::Rails.client
+          client.records.delete(
+            object: attio_object_type,
+            id: attio_record_id
+          )
+        end
+
+        def attio_attributes
+          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
+            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?
+          
+          condition = attio_sync_conditions
+          case condition
+          when Proc
+            instance_exec(&condition)
+          when Symbol, String
+            send(condition)
+          else
+            true
+          end
+        end
+
+        def should_remove_from_attio?
+          attio_record_id.present? && Attio::Rails.sync_enabled?
+        end
+
+        def attio_identifier
+          send(attio_identifier_attribute)
+        end
+      end
+    end
+  end
+end