attio-rails 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f87465ccc673d7f6303bb1f2452c34a04e9eeb8ae2a8dafc5eb10782d1b088e
-  data.tar.gz: 5528020745e15f607aed52d10fdd029614ef47a91604bd4b112c12ab2d5469a8
+  metadata.gz: 5a8102663f11e79d1701d5535c84d290bbe469eecff5dc9dc184cd32d3cbb6f1
+  data.tar.gz: 9c44c1dfec3c6ac14507073dadafad96d2c8778f7243476324244757a13da768
 SHA512:
-  metadata.gz: 499bc5887d50c6b9dfc1e8941cd3b9c22779b81e2d4d716c05bdd9a96afb0af845c7b1a1cb21b0ff28a49430e451b74b8d3e6d085d4f173bcd69ce7234224f33
-  data.tar.gz: 02dd1be6cb69a0689b2de7e62c590380b8a3be7eca40795af4b1df3f477dcf47fd99523eb5dc631a45910771eed515dfaad5dfdd87aa2d9fad5e70053ff73f40
+  metadata.gz: 8b36523aa233614f1d9ce43ad20b18080c7459f6bda2e2da67114b926a2dfa10a60cf569e9866ca86a644032daf8c27b6050bd7e99e57366202b5ef8e74255e9
+  data.tar.gz: db16d544bcdd62cd6f9f7434c203d252b15eeafb2541a84d57b1196901f3c0ea6a3ac8682b2fc903a38cd8b978e6458208a3380b262374417bc252e2dbf7faf0

data/.github/workflows/{release.yml → build-and-publish.yml}

@@ -1,4 +1,4 @@
-name: Release
+name: Build and Publish
 
 on:
   push:
@@ -6,7 +6,7 @@ on:
       - 'v*.*.*'
 
 jobs:
-  release:
+  build-and-publish:
     runs-on: ubuntu-latest
     
     permissions:
@@ -30,7 +30,7 @@ jobs:
         mkdir -p ~/.gem
         cat > ~/.gem/credentials << EOF
         ---
-        :rubygems_api_key: ${{ secrets.RUBYGEMS_API_KEY }}
+        :rubygems_api_key: ${{ secrets.RUBYGEMS_AUTH_TOKEN }}
         EOF
         chmod 0600 ~/.gem/credentials
 
@@ -58,13 +58,3 @@ jobs:
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-    - name: Update GitHub Pages with documentation
-      run: |
-        git config --local user.email "action@github.com"
-        git config --local user.name "GitHub Action"
-        git checkout --orphan gh-pages
-        git rm -rf .
-        cp -r docs/* .
-        git add -A
-        git commit -m "Update documentation for ${{ github.ref_name }}"
-        git push origin gh-pages --force

data/.github/workflows/ci.yml

@@ -48,7 +48,7 @@ jobs:
     
     - name: Upload coverage to Codecov
       if: matrix.ruby-version == '3.4' && matrix.rails-version == '8.0'
-      uses: codecov/codecov-action@v4
+      uses: codecov/codecov-action@v5
       with:
         files: ./coverage/coverage.xml,./coverage/.resultset.json
         flags: unittests

data/.github/workflows/docs.yml

@@ -2,7 +2,7 @@ name: Documentation
 
 on:
   push:
-    branches: [ main ]
+    branches: [ master ]
   workflow_dispatch:
 
 permissions:
@@ -28,7 +28,7 @@ jobs:
         bundler-cache: true
 
     - name: Setup Pages
-      uses: actions/configure-pages@v4
+      uses: actions/configure-pages@v5
 
     - name: Generate documentation
       run: |

data/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2025-01-11
+
+### Added
+- **BatchSync** class for efficient bulk synchronization operations
+- **ActiveJob integration** with dedicated `AttioSyncJob` for background processing
+- **Callbacks support** - `before_attio_sync` and `after_attio_sync` hooks
+- **Transform support** - Custom attribute transformation before syncing
+- **Error handlers** - Configurable error handling with `:on_error` option
+- **RSpec test helpers** - Comprehensive testing utilities for Attio operations
+- **Concepts documentation** - Detailed architecture guide with Mermaid diagrams
+- **Configuration enhancements**:
+  - `queue` option for ActiveJob queue configuration
+  - `raise_on_missing_record` option for missing record behavior
+- **100% test coverage** with comprehensive test suite
+
+### Changed
+- Enhanced `Syncable` concern with callbacks and transforms
+- Improved error handling with environment-specific behavior
+- Renamed GitHub Actions workflow from `release.yml` to `build-and-publish.yml`
+- Updated README with comprehensive examples and usage patterns
+
+### Fixed
+- RuboCop linting issues for better code quality
+- Test coverage gaps - achieved 100% coverage
+
+## [0.1.2] - 2025-01-11
+
+### Changed
+- Updated attio dependency to 0.1.3
+- Applied Stripe's RuboCop configuration
+- Achieved 100% test coverage
+
+### Fixed
+- All RuboCop offenses auto-corrected
+- Test failures resolved
+
 ## [0.1.1] - 2025-01-11
 
 ### Added
@@ -44,5 +80,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Batch operations support
 - Custom field transformations
 
-[Unreleased]: https://github.com/idl3/attio-rails/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/idl3/attio-rails/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/idl3/attio-rails/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/idl3/attio-rails/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/idl3/attio-rails/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/idl3/attio-rails/releases/tag/v0.1.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

@@ -17,7 +17,7 @@ group :development, :test do
   gem "rspec-rails", "~> 6.0"
   gem "rubocop", "~> 1.50"
   gem "rubocop-rails", "~> 2.19"
-  gem "rubocop-rspec", "~> 2.19"
+  gem "rubocop-rspec", "~> 3.6"
   gem "simplecov", "~> 0.22"
   gem "simplecov-console", "~> 0.9"
   gem "sqlite3", "~> 1.4"

data/lib/attio/rails/rspec/helpers.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Attio
+  module Rails
+    module RSpec
+      # RSpec helper methods for testing Attio Rails integration
+      #
+      # @example Including in your specs
+      #   RSpec.configure do |config|
+      #     config.include Attio::Rails::RSpec::Helpers
+      #   end
+      #
+      # @example Basic usage
+      #   it 'syncs to Attio' do
+      #     stub_attio_client
+      #
+      #     user = User.create!(email: 'test@example.com')
+      #     expect(user.attio_record_id).to eq('attio-test-id')
+      #   end
+      #
+      # @example Testing with expectations
+      #   it 'sends correct attributes' do
+      #     expect_attio_sync(
+      #       object: 'people',
+      #       attributes: { email: 'test@example.com' }
+      #     ) do
+      #       User.create!(email: 'test@example.com')
+      #     end
+      #   end
+      module Helpers
+        # Stub the Attio client and records API
+        #
+        # @return [Hash{Symbol => RSpec::Mocks::Double}] Hash with :client and :records doubles
+        #
+        # @example
+        #   stubs = stub_attio_client
+        #   allow(stubs[:records]).to receive(:create).and_return(response)
+        def stub_attio_client
+          client = instance_double(Attio::Client)
+          records = instance_double(Attio::Resources::Records)
+
+          allow(Attio::Rails).to receive(:client).and_return(client)
+          allow(client).to receive(:records).and_return(records)
+
+          { client: client, records: records }
+        end
+
+        # Stub Attio create operations
+        #
+        # @param response [Hash] Custom response to return (default: { "data" => { "id" => "attio-test-id" } })
+        # @return [Hash{Symbol => RSpec::Mocks::Double}] Hash with :client and :records doubles
+        #
+        # @example
+        #   stub_attio_create
+        #   User.create!(email: 'test@example.com')
+        #
+        # @example With custom response
+        #   stub_attio_create('data' => { 'id' => 'custom-id' })
+        def stub_attio_create(response = { "data" => { "id" => "attio-test-id" } })
+          stubs = stub_attio_client
+          allow(stubs[:records]).to receive(:create).and_return(response)
+          stubs
+        end
+
+        # Stub Attio update operations
+        #
+        # @param response [Hash] Custom response to return
+        # @return [Hash{Symbol => RSpec::Mocks::Double}] Hash with :client and :records doubles
+        #
+        # @example
+        #   stub_attio_update
+        #   user.update!(name: 'New Name')
+        def stub_attio_update(response = { "data" => { "id" => "attio-test-id" } })
+          stubs = stub_attio_client
+          allow(stubs[:records]).to receive(:update).and_return(response)
+          stubs
+        end
+
+        # Stub Attio delete operations
+        #
+        # @param response [Hash] Custom response to return
+        # @return [Hash{Symbol => RSpec::Mocks::Double}] Hash with :client and :records doubles
+        #
+        # @example
+        #   stub_attio_delete
+        #   user.destroy!
+        def stub_attio_delete(response = { "data" => { "deleted" => true } })
+          stubs = stub_attio_client
+          allow(stubs[:records]).to receive(:delete).and_return(response)
+          stubs
+        end
+
+        # Expect a sync to Attio with specific parameters
+        #
+        # @param object [String] Expected Attio object type
+        # @param attributes [Hash, nil] Expected attributes (nil to match any)
+        # @yield Block to execute that should trigger the sync
+        # @return [Hash{Symbol => RSpec::Mocks::Double}] Hash with :client and :records doubles
+        #
+        # @example
+        #   expect_attio_sync(object: 'people', attributes: { email: 'test@example.com' }) do
+        #     User.create!(email: 'test@example.com')
+        #   end
+        def expect_attio_sync(object:, attributes: nil)
+          stubs = stub_attio_client
+
+          if attributes
+            expect(stubs[:records]).to receive(:create).with(
+              object: object,
+              data: { values: attributes }
+            ).and_return({ "data" => { "id" => "attio-test-id" } })
+          else
+            expect(stubs[:records]).to receive(:create).with(
+              hash_including(object: object)
+            ).and_return({ "data" => { "id" => "attio-test-id" } })
+          end
+
+          yield if block_given?
+
+          stubs
+        end
+
+        # Expect no sync to Attio
+        #
+        # @yield Block to execute that should not trigger any sync
+        # @return [Hash{Symbol => RSpec::Mocks::Double}] Hash with :client and :records doubles
+        #
+        # @example
+        #   expect_no_attio_sync do
+        #     with_attio_sync_disabled do
+        #       User.create!(email: 'test@example.com')
+        #     end
+        #   end
+        def expect_no_attio_sync
+          stubs = stub_attio_client
+
+          expect(stubs[:records]).not_to receive(:create)
+          expect(stubs[:records]).not_to receive(:update)
+
+          yield if block_given?
+
+          stubs
+        end
+
+        # Temporarily disable Attio syncing
+        #
+        # @yield Block to execute with syncing disabled
+        #
+        # @example
+        #   with_attio_sync_disabled do
+        #     User.create!(email: 'test@example.com') # Won't sync
+        #   end
+        def with_attio_sync_disabled
+          original_value = Attio::Rails.configuration.sync_enabled
+          Attio::Rails.configure { |c| c.sync_enabled = false }
+
+          yield
+        ensure
+          Attio::Rails.configure { |c| c.sync_enabled = original_value }
+        end
+
+        # Temporarily enable background sync
+        #
+        # @yield Block to execute with background sync enabled
+        #
+        # @example
+        #   with_attio_background_sync do
+        #     User.create!(email: 'test@example.com') # Will sync in background
+        #   end
+        #   expect(attio_sync_jobs.size).to eq(1)
+        def with_attio_background_sync
+          original_value = Attio::Rails.configuration.background_sync
+          Attio::Rails.configure { |c| c.background_sync = true }
+
+          yield
+        ensure
+          Attio::Rails.configure { |c| c.background_sync = original_value }
+        end
+
+        # Get all enqueued AttioSyncJob jobs
+        #
+        # @return [Array<Hash>] Array of enqueued job hashes
+        #
+        # @example
+        #   User.create!(email: 'test@example.com')
+        #   expect(attio_sync_jobs.size).to eq(1)
+        #   expect(attio_sync_jobs.first[:args]).to include('model_name' => 'User')
+        def attio_sync_jobs
+          ActiveJob::Base.queue_adapter.enqueued_jobs.select do |job|
+            job[:job] == AttioSyncJob
+          end
+        end
+
+        # Clear all enqueued AttioSyncJob jobs
+        #
+        # @return [Array<Hash>] The deleted jobs
+        #
+        # @example
+        #   clear_attio_sync_jobs
+        #   expect(attio_sync_jobs).to be_empty
+        def clear_attio_sync_jobs
+          ActiveJob::Base.queue_adapter.enqueued_jobs.delete_if do |job|
+            job[:job] == AttioSyncJob
+          end
+        end
+      end
+    end
+  end
+end

data/lib/attio/rails/rspec/matchers.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Attio
+  module Rails
+    module RSpec
+      module Matchers
+        ::RSpec::Matchers.define :sync_to_attio do |expected|
+          match do |actual|
+            return false unless actual.class.respond_to?(:attio_object_type)
+
+            if expected
+              actual.class.attio_object_type == expected[:object] || expected[:object_type]
+            else
+              actual.class.attio_object_type.present?
+            end
+          end
+
+          failure_message do |actual|
+            if actual.class.respond_to?(:attio_object_type)
+              expected_obj = expected[:object] || expected[:object_type]
+              actual_obj = actual.class.attio_object_type
+              "expected #{actual.class} to sync to Attio object '#{expected_obj}' but syncs to '#{actual_obj}'"
+            else
+              "expected #{actual.class} to include Attio::Rails::Concerns::Syncable"
+            end
+          end
+
+          failure_message_when_negated do |actual|
+            "expected #{actual.class} not to sync to Attio"
+          end
+
+          description do
+            "sync to Attio"
+          end
+        end
+
+        ::RSpec::Matchers.define :have_attio_attribute do |attio_attr|
+          match do |actual|
+            return false unless actual.class.respond_to?(:attio_attribute_mapping)
+
+            mapping = actual.class.attio_attribute_mapping
+            if @mapped_to
+              mapping[attio_attr] == @mapped_to
+            else
+              mapping.key?(attio_attr)
+            end
+          end
+
+          chain :mapped_to do |local_attr|
+            @mapped_to = local_attr
+          end
+
+          failure_message do |actual|
+            if actual.class.respond_to?(:attio_attribute_mapping)
+              mapping = actual.class.attio_attribute_mapping
+              if @mapped_to
+                actual_mapping = mapping[attio_attr]
+                "expected #{actual.class} to map Attio attribute '#{attio_attr}' to '#{@mapped_to}' " \
+                  "but it maps to '#{actual_mapping}'"
+              else
+                available_attrs = mapping.keys.join(", ")
+                "expected #{actual.class} to have Attio attribute '#{attio_attr}' but has #{available_attrs}"
+              end
+            else
+              "expected #{actual.class} to include Attio::Rails::Concerns::Syncable"
+            end
+          end
+
+          description do
+            if @mapped_to
+              "have Attio attribute '#{attio_attr}' mapped to '#{@mapped_to}'"
+            else
+              "have Attio attribute '#{attio_attr}'"
+            end
+          end
+        end
+
+        ::RSpec::Matchers.define :enqueue_attio_sync_job do # rubocop:disable Metrics/BlockLength
+          supports_block_expectations
+
+          match do |block|
+            initial_jobs = attio_sync_jobs.dup
+            block.call
+            new_jobs = attio_sync_jobs - initial_jobs
+            @actual_count = new_jobs.size
+
+            if @expected_count
+              @actual_count == @expected_count
+            elsif @expected_action
+              new_jobs.any? { |job| job[:args].first["action"]["value"] == @expected_action.to_s }
+            else
+              @actual_count > 0
+            end
+          end
+
+          chain :with_action do |action|
+            @expected_action = action
+          end
+
+          chain :exactly do |count|
+            @expected_count = count
+          end
+
+          failure_message do
+            build_failure_message
+          end
+
+          failure_message_when_negated do
+            "expected not to enqueue AttioSyncJob but #{@actual_count} were enqueued"
+          end
+
+          description do
+            build_description
+          end
+
+          private def build_failure_message
+            if @expected_count
+              "expected to enqueue #{@expected_count} AttioSyncJob(s) but enqueued #{@actual_count}"
+            elsif @expected_action
+              "expected to enqueue AttioSyncJob with action '#{@expected_action}'"
+            else
+              "expected to enqueue AttioSyncJob but none were enqueued"
+            end
+          end
+
+          private def build_description
+            if @expected_count
+              "enqueue #{@expected_count} AttioSyncJob(s)"
+            elsif @expected_action
+              "enqueue AttioSyncJob with action '#{@expected_action}'"
+            else
+              "enqueue AttioSyncJob"
+            end
+          end
+
+          private def attio_sync_jobs
+            ActiveJob::Base.queue_adapter.enqueued_jobs.select do |job|
+              job[:job] == AttioSyncJob
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/attio/rails/rspec.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "attio/rails/rspec/helpers"
+require "attio/rails/rspec/matchers"
+
+RSpec.configure do |config|
+  config.include Attio::Rails::RSpec::Helpers, type: :model
+  config.include Attio::Rails::RSpec::Matchers, type: :model
+end

data/lib/attio/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Attio
   module Rails
-    VERSION = "0.1.2"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: attio-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Ernest Sim
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: attio
@@ -59,9 +60,9 @@ extra_rdoc_files: []
 files:
 - ".codecov.yml"
 - ".github/dependabot.yml"
+- ".github/workflows/build-and-publish.yml"
 - ".github/workflows/ci.yml"
 - ".github/workflows/docs.yml"
-- ".github/workflows/release.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -69,6 +70,7 @@ files:
 - ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- CONCEPTS.md
 - CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
@@ -83,6 +85,9 @@ files:
 - lib/attio/rails/concerns/syncable.rb
 - lib/attio/rails/configuration.rb
 - lib/attio/rails/railtie.rb
+- lib/attio/rails/rspec.rb
+- lib/attio/rails/rspec/helpers.rb
+- lib/attio/rails/rspec/matchers.rb
 - lib/attio/rails/version.rb
 - lib/generators/attio/install/install_generator.rb
 - lib/generators/attio/install/templates/README.md
@@ -99,6 +104,7 @@ metadata:
   source_code_uri: https://github.com/idl3/attio-rails
   changelog_uri: https://github.com/idl3/attio-rails/blob/main/CHANGELOG.md
   documentation_uri: https://idl3.github.io/attio-rails
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -113,7 +119,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: Rails integration for the Attio API client
 test_files: []