external_id 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7f37fe1f61ae7cc606c98a516bcbf92158799383751ecfa602b3b29c32a7da2
-  data.tar.gz: 71a51fe88cebf3fe95516cd87c4a173d111925cdf1da6fcf3c5a8caddebc299e
+  metadata.gz: 1b9df2ebbd5ffd553c97841c5d7b4b66f5a4c5ad03e6c6514ce81d05f8fcc476
+  data.tar.gz: f591813e0d6ac93edb75491131543fd52ea0ccf10e71e95bc46ddec6cfe5fcc6
 SHA512:
-  metadata.gz: 911f2c68eff82fc94075e67f295f6c9a49324013ea9636c845705bc4d9bf8c07282d432d7cf691ca37c579b4d256a20397a7a0ef3c69abcbb1999a28d4f5ba80
-  data.tar.gz: 24c2e9299bb4658cda2dc0a0c0d0a805036181cf0f89096074f3fb60b831251e47be98b1e74aa97cd1e8ca250e678fecb171912d691baf5a20892d8dd8100883
+  metadata.gz: 39983d6348cecc46842550d55a688b85dc32adc865c2e946b0d0eb4a2a1f71fa3db8cdaf637963be9e1dcd805ea167aa493bce0184c000440b3ff97e19ea812e
+  data.tar.gz: a043ce4201d839ad871040314eab48517426a8931cbc2d046faddef1dbe85be57d6987f2aeb6ef96d0b412d42a3ab8fdcfe58b9c7571f27eaca9b40082ce3731

data/CHANGELOG.md

@@ -1,11 +1,15 @@
 ## [Unreleased]
 
+## [0.1.1] - 2025-12-02
+- add installer for external_id factory
+- fix: copy migration to correct path
+
 ## [0.1.0] - 2025-12-02
 
 - Initial release
 - Polymorphic external ID associations for Rails models
 - `ExternalId` model for database-backed storage
-- `ExternalIdValue` value object for clean data handling
+- `ExternalId::Value` value object for clean data handling
 - `WithExternalId` concern for easy model integration
 - Configurable providers with enum support
 - UUID support for distributed systems

data/README.md

@@ -63,6 +63,11 @@ ExternalId.configure do |config|
 
   # Optional: Use UUID for primary keys (default: true)
   # config.use_uuid = true
+
+  # Optional: Enable auditing with the audited gem (if loaded)
+  # Default: true
+  # Set to false if you don't want ExternalId records to be audited
+  # config.enable_auditing = true
 end
 ```
 
@@ -88,8 +93,8 @@ customer = Customer.find(123)
 # Option 1: Using keyword arguments
 customer.add_external_id(provider: 'raynet', id: 'R-12345')
 
-# Option 2: Using an ExternalIdValue object
-external_id = ExternalId::ExternalIdValue.new(provider: 'salesforce', id: 'SF-67890')
+# Option 2: Using an ExternalId::Value object
+external_id = ExternalId::Value.new(provider: 'salesforce', id: 'SF-67890')
 customer.add_external_id(external_id)
 ```
 
@@ -111,7 +116,7 @@ Customer.find_by_external_id('unknown', '123')  # => ArgumentError
 ```ruby
 customer = Customer.find(123)
 
-# Returns an ExternalIdValue object
+# Returns an ExternalId::Value object
 external_id = customer.external_id
 
 if external_id.present?
@@ -132,7 +137,7 @@ customer_without_eid.external_id.blank?  # => true
 customer = Customer.find(123)
 
 # Access the external_id record directly
-customer.eid  # => ExternalId::ExternalId instance or nil
+customer.eid  # => ExternalId::Record instance or nil
 
 # The association is dependent: :destroy
 # Deleting the customer will also delete the external_id
@@ -157,13 +162,13 @@ add_index :external_ids, [:provider, :resource_type, :resource_id],
 
 This ensures that each resource can only have one external ID per provider.
 
-## ExternalIdValue
+## ExternalId::Value
 
-The `ExternalIdValue` class is a value object that provides a clean interface for working with external IDs:
+The `ExternalId::Value` class is a value object that provides a clean interface for working with external IDs:
 
 ```ruby
 # Create a value object
-eid = ExternalId::ExternalIdValue.new(provider: 'raynet', id: '12345')
+eid = ExternalId::Value.new(provider: 'raynet', id: '12345')
 
 # Check presence
 eid.present?  # => true
@@ -179,14 +184,14 @@ eid.to_hash   # => { provider: 'raynet', id: '12345' }
 eid.to_a      # => ['raynet', '12345']
 
 # Create from array
-ExternalId::ExternalIdValue.from_array(['raynet', '12345'])
+ExternalId::Value.from_array(['raynet', '12345'])
 
 # Create blank value
-ExternalId::ExternalIdValue.blank  # => blank instance
+ExternalId::Value.blank  # => blank instance
 
 # Comparison
-eid1 = ExternalId::ExternalIdValue.new(provider: 'raynet', id: '123')
-eid2 = ExternalId::ExternalIdValue.new(provider: 'raynet', id: '123')
+eid1 = ExternalId::Value.new(provider: 'raynet', id: '123')
+eid2 = ExternalId::Value.new(provider: 'raynet', id: '123')
 eid1 == eid2  # => true
 ```
 
@@ -203,13 +208,13 @@ class ApplicationRecord < ActiveRecord::Base
 end
 
 # Add custom scopes
-class ExternalId::ExternalId
+class ExternalId::Record
   scope :raynet, -> { where(provider: 'raynet') }
   scope :customers, -> { where(resource_type: 'Customer') }
 end
 
 # Use them
-ExternalId::ExternalId.raynet.customers
+ExternalId::Record.raynet.customers
 ```
 
 ### Handling multiple providers
@@ -228,6 +233,47 @@ customer.add_external_id(provider: 'raynet', id: 'R-99999')  # => ActiveRecord::
 # Note: Currently limited to one external_id per resource
 ```
 
+### Auditing with the audited gem
+
+If you have the `audited` gem loaded in your application, the `ExternalId` model will automatically track all changes to external ID records. This includes tracking changes to:
+- `provider` attribute
+- `external_id` attribute
+- `resource` polymorphic association
+
+Auditing is enabled by default when the audited gem is present. You can disable it in your initializer:
+
+```ruby
+ExternalId.configure do |config|
+  config.enable_auditing = false
+end
+```
+
+To access the audit history of an external ID record:
+
+```ruby
+external_id_record = ExternalId::Record.find(some_id)
+
+# Get all audits for this record
+external_id_record.audits
+
+# Get the last audit
+external_id_record.audits.last
+
+# Access audit details
+audit = external_id_record.audits.last
+audit.action        # => "create", "update", or "destroy"
+audit.audited_changes # => Hash of changed attributes
+audit.created_at    # => When the change occurred
+audit.user          # => The user who made the change (if set)
+```
+
+Note: Make sure you've run the audited gem's generator to create the `audits` table:
+
+```bash
+rails generate audited:install
+rails db:migrate
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/external_id/concerns/with_external_id.rb

@@ -5,7 +5,7 @@ module ExternalId
     extend ActiveSupport::Concern
 
     included do
-      has_one :eid, class_name: 'ExternalId::ExternalId', as: :resource, dependent: :destroy
+      has_one :eid, class_name: 'ExternalId::Record', as: :resource, dependent: :destroy
     end
 
     class_methods do
@@ -16,22 +16,22 @@ module ExternalId
                 "Provider must be one of #{providers.keys}, was '#{provider}'"
         end
 
-        ::ExternalId::ExternalId.find_by(provider: provider, external_id: external_id, resource_type: name)&.resource
+        ::ExternalId::Record.find_by(provider: provider, external_id: external_id, resource_type: name)&.resource
       end
     end
 
     def add_external_id(external_id_object = nil, provider: nil, id: nil)
       if external_id_object.blank? && provider.blank? && id.blank?
-        raise 'Either ExternalIdValue or provider and id are required'
+        raise 'Either ExternalId::Value or provider and id are required'
       end
 
-      eid = external_id_object.is_a?(::ExternalId::ExternalIdValue) ? external_id_object : ::ExternalId::ExternalIdValue.new(provider: provider, id: id)
+      eid = external_id_object.is_a?(::ExternalId::Value) ? external_id_object : ::ExternalId::Value.new(provider: provider, id: id)
 
-      ::ExternalId::ExternalId.find_or_create_by!(provider: eid.provider, external_id: eid.id, resource: self)
+      ::ExternalId::Record.find_or_create_by!(provider: eid.provider, external_id: eid.id, resource: self)
     end
 
     def external_id
-      ::ExternalId::ExternalIdValue.from_model(eid)
+      ::ExternalId::Value.from_model(eid)
     end
   end
 end

data/lib/external_id/configuration.rb

@@ -2,12 +2,13 @@
 
 module ExternalId
   class Configuration
-    attr_accessor :providers, :base_class, :use_uuid
+    attr_accessor :providers, :base_class, :use_uuid, :enable_auditing
 
     def initialize
       @providers = {}
       @base_class = 'ActiveRecord::Base'
       @use_uuid = true
+      @enable_auditing = true
     end
 
     def providers=(value)

data/lib/external_id/models/{external_id.rb → record.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ExternalId
-  class ExternalId < ActiveRecord::Base
+  class Record < ActiveRecord::Base
     self.table_name = 'external_ids'
 
     belongs_to :resource, polymorphic: true
@@ -36,10 +36,10 @@ module ExternalId
     # Call setup when the class is loaded
     def self.inherited(subclass)
       super
-      subclass.setup_enum! if subclass == ExternalId::ExternalId
+      subclass.setup_enum! if subclass == ExternalId::Record
     end
   end
 end
 
 # Setup enum after configuration
-ExternalId::ExternalId.setup_enum! if defined?(Rails) && Rails.application
+ExternalId::Record.setup_enum! if defined?(Rails) && Rails.application

data/lib/external_id/models/{external_id_value.rb → value.rb}

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module ExternalId
-  # ExternalId value object
-  class ExternalIdValue
+  # ID Value value object
+  class Value
     include ActiveModel::Model
     include ActiveModel::Attributes
 
@@ -48,7 +48,7 @@ module ExternalId
     end
 
     def ==(other)
-      return false unless other.is_a?(ExternalIdValue)
+      return false unless other.is_a?(::ExternalId::Value)
 
       provider == other.provider && id == other.id
     end

data/lib/external_id/railtie.rb

@@ -6,6 +6,12 @@ module ExternalId
       ActiveSupport.on_load(:active_record) do
         # Make the concern available to all ActiveRecord models
         # Users will still need to explicitly include it
+
+        # Enable auditing if the audited gem is loaded and configured
+        # This runs after initializers so user configuration is available
+        if defined?(Audited) && ::ExternalId.configuration.enable_auditing
+          ::ExternalId::Record.audited
+        end
       end
     end
   end

data/lib/external_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ExternalId
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/external_id.rb

@@ -5,8 +5,8 @@ require 'active_support'
 
 require_relative 'external_id/version'
 require_relative 'external_id/configuration'
-require_relative 'external_id/models/external_id_value'
-require_relative 'external_id/models/external_id'
+require_relative 'external_id/models/value'
+require_relative 'external_id/models/record'
 require_relative 'external_id/concerns/with_external_id'
 
 module ExternalId

data/lib/generators/external_id/install/templates/README

@@ -11,24 +11,28 @@ Next steps:
    rails db:migrate
 
 3. Include the concern in your models:
-   
+
    class Customer < ApplicationRecord
      include ExternalId::WithExternalId
    end
 
 4. Start using external IDs in your application:
-   
+
    # Add an external ID to a record
    customer.add_external_id(provider: 'raynet', id: '12345')
-   
+
    # Find a record by external ID
    customer = Customer.find_by_external_id('raynet', '12345')
-   
+
    # Get the external ID value object
    external_id = customer.external_id
    external_id.provider  # => 'raynet'
    external_id.id        # => '12345'
 
+5. If FactoryBot was detected, a factory file was created in your
+   test factories directory. Customize the :external_id factory
+   to link to your models.
+
 For more information, see: https://github.com/yourusername/external-id
 
 ===============================================================================

data/lib/generators/external_id/install/templates/external_ids_factory.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :external_id, class: 'ExternalId::Record' do
+    provider { 'default_provider' }
+    sequence(:external_id) { |n| "ext-#{n}" }
+    # association :resource, factory: :your_model
+  end
+end

data/lib/generators/external_id/install/templates/initializer.rb

@@ -20,4 +20,9 @@ ExternalId.configure do |config|
   # Use UUID for primary keys (recommended for distributed systems)
   # Default: true
   # config.use_uuid = true
+
+  # Enable auditing with the audited gem (if loaded)
+  # Default: true
+  # Set to false if you don't want ExternalId records to be audited
+  # config.enable_auditing = true
 end

data/lib/generators/external_id/install/templates/migration.rb.tt

@@ -2,10 +2,10 @@
 
 class CreateExternalIds < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
-    create_table :external_ids<%= ', id: :uuid' if ExternalId.configuration.use_uuid %> do |t|
+    create_table :external_ids<%= ', id: :uuid' if @use_uuid %> do |t|
       t.string :provider, null: false, index: true
       t.string :external_id, null: false
-      t.references :resource, polymorphic: true, null: false, index: true<%= ', type: :uuid' if ExternalId.configuration.use_uuid %>
+      t.references :resource, polymorphic: true, null: false, index: true<%= ', type: :uuid' if @use_uuid %>
 
       t.timestamps
     end

data/lib/generators/external_id/install_generator.rb

@@ -16,8 +16,21 @@ module ExternalId
         template 'initializer.rb', 'config/initializers/external_id.rb'
       end
 
-      def create_migration
-        migration_template 'migration.rb.tt', File.join(db_migrate_path, 'create_external_ids.rb')
+      def copy_migration
+        @use_uuid = ExternalId.configuration.use_uuid rescue false
+        migration_template 'migration.rb.tt', 'db/migrate/create_external_ids.rb'
+      end
+
+      def copy_factory
+        return unless factory_bot_available?
+
+        test_dir = detect_test_directory
+        return unless test_dir
+
+        factories_dir = File.join(test_dir, 'factories')
+        empty_directory factories_dir unless File.directory?(factories_dir)
+
+        template 'external_ids_factory.rb', File.join(factories_dir, 'external_ids.rb')
       end
 
       def show_readme
@@ -26,13 +39,30 @@ module ExternalId
 
       private
 
-      def db_migrate_path
-        if defined?(Rails.application) && Rails.application.config.paths['db/migrate']
-          Rails.application.config.paths['db/migrate'].to_a.first
-        else
-          'db/migrate'
+      def factory_bot_available?
+        return @factory_bot_available if defined?(@factory_bot_available)
+
+        @factory_bot_available = begin
+          # Check Gemfile for factory_bot
+          gemfile_path = File.join(destination_root, 'Gemfile')
+          if File.exist?(gemfile_path)
+            gemfile_content = File.read(gemfile_path)
+            gemfile_content.match?(/factory_bot|factory_girl/)
+          else
+            false
+          end
         end
       end
+
+      def detect_test_directory
+        # Check common test directory names in order of preference
+        %w[spec test rspec].each do |dir|
+          path = File.join(destination_root, dir)
+          return dir if File.directory?(path)
+        end
+
+        nil
+      end
     end
   end
 end

data/sig/external_id.rbs

@@ -45,16 +45,16 @@ module ExternalId
   end
 
   # Value object for external IDs
-  class ExternalIdValue
+  class Value
     include ActiveModel::Model
     include ActiveModel::Attributes
 
     attr_accessor provider: String?
     attr_accessor id: String?
 
-    def self.blank: () -> ExternalIdValue
-    def self.from_model: (ExternalId?) -> ExternalIdValue
-    def self.from_array: (Array[String?]?) -> ExternalIdValue
+    def self.blank: () -> Value
+    def self.from_model: (ExternalId?) -> Value
+    def self.from_array: (Array[String?]?) -> Value
 
     def initialize: (?provider: String? | Symbol?, ?id: String?) -> void
     def present?: () -> bool
@@ -98,8 +98,8 @@ module ExternalId
     # Instance methods available to including classes
     def eid: () -> ExternalId?
     def eid=: (ExternalId?) -> ExternalId?
-    def add_external_id: (?ExternalIdValue?, ?provider: String? | Symbol?, ?id: String?) -> ExternalId
-    def external_id: () -> ExternalIdValue
+    def add_external_id: (?Value?, ?provider: String? | Symbol?, ?id: String?) -> ExternalId
+    def external_id: () -> Value
 
     # Class methods added to including classes
     module ClassMethods

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: external_id
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Tomáš Landovský
@@ -143,11 +143,12 @@ files:
 - lib/external_id.rb
 - lib/external_id/concerns/with_external_id.rb
 - lib/external_id/configuration.rb
-- lib/external_id/models/external_id.rb
-- lib/external_id/models/external_id_value.rb
+- lib/external_id/models/record.rb
+- lib/external_id/models/value.rb
 - lib/external_id/railtie.rb
 - lib/external_id/version.rb
 - lib/generators/external_id/install/templates/README
+- lib/generators/external_id/install/templates/external_ids_factory.rb
 - lib/generators/external_id/install/templates/initializer.rb
 - lib/generators/external_id/install/templates/migration.rb.tt
 - lib/generators/external_id/install_generator.rb