loggable_activity 0.1.39 → 0.1.40

data/lib/loggable_activity/encryption_key.rb

@@ -1,44 +1,111 @@
 # frozen_string_literal: true
 
-# This the key used to unlock the data for one payload.
-# When deleted only the encryption_key field is deleted.
-
 module LoggableActivity
+  # This class represents the encryption key used to unlock the data for one payload.
+  # When deleted, only the encryption_key field is deleted.
   class EncryptionKey < ActiveRecord::Base
     self.table_name = 'loggable_encryption_keys'
-    require 'securerandom'
+
+    # Associations
     belongs_to :record, polymorphic: true, optional: true
     belongs_to :parrent_key, class_name: 'LoggableActivity::EncryptionKey', optional: true,
                              foreign_key: 'parrent_key_id'
 
+    # Marks the encryption key as deleted by updating the key to nil.
     def mark_as_deleted
       update(key: nil)
       parrent_key.mark_as_deleted if parrent_key.present?
     end
 
-    def self.for_record_by_type_and_id(record_type, record_id, parrent_key = nil)
-      enctyption_key = find_by(record_type:, record_id:)
-
-      return enctyption_key if enctyption_key
+    # Returns an encryption key for a record by its type and ID, optionally using a parent key.
+    #
+    #  @param record_type [String] The type of the record.
+    #  @param record_id [Integer] The ID of the record.
+    #  @param parent_key [LoggableActivity::EncryptionKey, nil] The parent encryption key, if any.
+    #  @return [LoggableActivity::EncryptionKey] The encryption key for the record.
+    #
+    # Example:
+    #  LoggableActivity::EncryptionKey.for_record_by_type_and_id('User', 1)
+    #
+    # Returns:
+    #  {
+    #    :id => 39,
+    #    :parrent_key_id => 38,
+    #    :key => "a8f4774e7f42eb253045a4db7de7b79e",
+    #    :record_type => "User",
+    #    :record_id => 1
+    #  }
+    #
+    def self.for_record_by_type_and_id(record_type, record_id, parent_key = nil)
+      encryption_key = find_by(record_type:, record_id:)
+      return encryption_key if encryption_key
 
-      create_encryption_key(record_type, record_id, parrent_key)
+      create_encryption_key(record_type, record_id, parent_key)
     end
 
-    def self.for_record(record, parrent_key = nil)
+    # Returns an encryption key for a record, optionally using a parent key.
+    #
+    #  @param record [ActiveRecord::Base] The record for which to get the encryption key.
+    #  @param parent_key [LoggableActivity::EncryptionKey, nil] The parent encryption key, if any.
+    #  @return [LoggableActivity::EncryptionKey] The encryption key for the record.
+    #
+    # Example:
+    #  user = User.find(1)
+    #  LoggableActivity::EncryptionKey.for_record(user)
+    #
+    # Returns:
+    #  {
+    #    :id => 39,
+    #    :parrent_key_id => 38,
+    #    :key => "a8f4774e7f42eb253045a4db7de7b79e",
+    #    :record_type => "User",
+    #    :record_id => 1
+    #  }
+    #
+    def self.for_record(record, parent_key = nil)
       encryption_key = find_by(record:)
       return encryption_key if encryption_key
 
-      create_encryption_key(record.class.name, record.id, parrent_key)
+      create_encryption_key(record.class.name, record.id, parent_key)
     end
 
-    def self.create_encryption_key(record_type, record_id, parrent_key = nil)
-      if parrent_key
-        create(record_type:, record_id:, key: random_key, parrent_key_id: parrent_key.id)
+    # Creates an encryption key for a record, optionally using a parent key.
+    #
+    #  @param record_type [String] The type of the record.
+    #  @param record_id [Integer] The ID of the record.
+    #  @param parent_key [LoggableActivity::EncryptionKey, nil] The parent encryption key, if any.
+    #  @return [LoggableActivity::EncryptionKey] The created encryption key.
+    #
+    # Example:
+    #  LoggableActivity::EncryptionKey.create_encryption_key('User', 1)
+    #
+    # Returns:
+    #  {
+    #    :id => 39,
+    #    :parrent_key_id => 38,
+    #    :key => "a8f4774e7f42eb253045a4db7de7b79e",
+    #    :record_type => "User",
+    #    :record_id => 1
+    #  }
+    #
+    def self.create_encryption_key(record_type, record_id, parent_key = nil)
+      if parent_key
+        create(record_type:, record_id:, key: random_key, parent_key_id: parent_key.id)
       else
         create(record_type:, record_id:, key: random_key)
       end
     end
 
+    # Generates a random encryption key.
+    #
+    #  @return [String] The generated encryption key.
+    #
+    # Example:
+    #  LoggableActivity::EncryptionKey.random_key
+    #
+    # Returns:
+    #  "a8f4774e7f42eb253045a4db7de7b79e"
+    #
     def self.random_key
       SecureRandom.hex(16)
     end

data/lib/loggable_activity/hooks.rb

@@ -6,17 +6,19 @@ require 'loggable_activity/payloads_builder'
 require 'loggable_activity/update_payloads_builder'
 
 module LoggableActivity
+  # This module provides hooks for creating activities when included in a model.
   module Hooks
     extend ActiveSupport::Concern
     include LoggableActivity::PayloadsBuilder
     include LoggableActivity::UpdatePayloadsBuilder
 
+    # The included hook sets up configuration and callback hooks for the model.
     included do
       config = LoggableActivity::Configuration.for_class(name)
-      if config.nil?
-        raise "Loggable::Configuration not found for #{name}, Please add it to 'config/loggable_activity.yaml'"
-      end
 
+      raise "Loggable::Configuration not found for #{name}, Please add it to 'config/loggable_activity.yaml'" if config.nil?
+
+      # Initializes attributes based on configuration.
       self.loggable_attrs = config&.fetch('loggable_attrs', []) || []
       self.relations = config&.fetch('relations', []) || []
       self.auto_log = config&.fetch('auto_log', []) || []
@@ -26,12 +28,13 @@ module LoggableActivity
       after_create :log_create_activity
       after_update :log_update_activity
       before_destroy :log_destroy_activity
-
-      # has_one: encryption_key, as: :encryption_key, class_name: 'LoggableActivity::EncryptionKey'
     end
 
-    # This is the main method for logging activities.
-    # It is never called from the directly from the controller.
+    # Logs an activity with the specified action, actor, and params.
+    #
+    #   @param action [Symbol] The action to log (:create, :update, :destroy, or custom).
+    #   @param actor [Object] The actor performing the action.
+    #   @param params [Hash] Additional parameters for the activity.
     def log(action, actor: nil, params: {})
       @action = action
       @actor = actor || Thread.current[:current_user]

data/lib/loggable_activity/payload.rb

@@ -1,19 +1,20 @@
 # frozen_string_literal: true
 
-# This is the payload of the log. It contains the encrypted data of one record in the DB.
-# When the record is deleted, the encryption_key for the payload is deleted.
-# Payloads comes in different flavors.
-# The primary_payload is the payload that contains the parrent record.
-# When fecthing the attrs, they are packed differently depending on the payload_type.
-
 module LoggableActivity
+  # This class represents a payload in the log, containing encrypted data of one record in the database.
+  # When the record is deleted, the encryption key for the payload is also deleted.
+  # Payloads come in different types, each serving a specific purpose.
   class Payload < ActiveRecord::Base
     self.table_name = 'loggable_payloads'
-    belongs_to :record, polymorphic: true, optional: true
 
+    # Associations
     belongs_to :activity
     belongs_to :record, polymorphic: true, optional: true
+
+    # Validations
     validates :encrypted_attrs, presence: true
+
+    # Enumeration for different payload types
     enum payload_type: {
       primary_payload: 0,
       update_payload: 1,
@@ -21,6 +22,21 @@ module LoggableActivity
       previous_association: 3
     }
 
+    # Returns the decrypted attributes of the payload based on its type.
+    #
+    # @return [Hash] The decrypted attributes.
+    #
+    # Example:
+    #  payload.attrs
+    #
+    #  Returns:
+    #  {
+    #           "street" => "Machu Picchu",
+    #             "city" => "Aguas Calientes",
+    #          "country" => "Peru",
+    #      "postal_code" => "08680"
+    #  }
+    #
     def attrs
       return deleted_attrs if record.nil?
 
@@ -29,27 +45,38 @@ module LoggableActivity
         decrypted_attrs
       when 'update_payload'
         decrypted_update_attrs
-        # when 'destroy_payload'
-        #   destroy_payload_attrs
       end
     end
 
+    private
+
+    # Retrieves the encryption key for the payload.
+    #
+    # @return [String, nil] The encryption key.
     def payload_encryption_key
       @payload_encryption_key ||= LoggableActivity::EncryptionKey.for_record(record)&.key
     end
 
-    private
-
+    # Helper method to handle deleted attributes.
+    #
+    # @return [Hash] The hash with deleted attributes.
     def deleted_attrs
       encrypted_attrs.transform_values! { I18n.t('loggable.activity.deleted') }
     end
 
+    # Decrypts the 'from' and 'to' attributes in the update payload.
+    #
+    # @return [Array<Hash>] The array of decrypted changes.
     def decrypted_update_attrs
       encrypted_attrs['changes'].map do |change|
         decrypted_from_to_attr(change)
       end
     end
 
+    # Decrypts 'from' and 'to' attributes.
+    #
+    # @param change [Hash] The change hash containing 'from' and 'to' values.
+    # @return [Hash] The decrypted 'from' and 'to' values.
     def decrypted_from_to_attr(change)
       change.to_h do |key, value|
         from = decrypt_attr(value['from'])
@@ -58,12 +85,19 @@ module LoggableActivity
       end
     end
 
+    # Decrypts all attributes.
+    #
+    # @return [Hash] The decrypted attributes.
     def decrypted_attrs
       encrypted_attrs.each do |key, value|
         encrypted_attrs[key] = decrypt_attr(value)
       end
     end
 
+    # Decrypts a single attribute.
+    #
+    # @param value [String] The encrypted value to decrypt.
+    # @return [String] The decrypted value.
     def decrypt_attr(value)
       LoggableActivity::Encryption.decrypt(value, payload_encryption_key)
     end

data/lib/loggable_activity/payloads_builder.rb

@@ -1,9 +1,28 @@
 # frozen_string_literal: true
 
-# This is a factory for building payloads.
-
 module LoggableActivity
+  # This module is responsible for building payloads used in loggable activities.
   module PayloadsBuilder
+    # Builds payloads for the loggable activity.
+    #
+    #  Example:
+    #    build_payloads
+    #
+    #  Returns:
+    #   #<LoggableActivity::Payload:0x0000000109658718> {
+    #                    :id => 129,
+    #           :record_type => "Demo::Club",
+    #             :record_id => 4,
+    #       :encrypted_attrs => {
+    #           "name" => "z/jigjcm3Fb89L7QT8XiNhvVgjtRXKkmg/xohR6wIc0=\n"
+    #       },
+    #          :payload_type => "current_association",
+    #            :data_owner => nil,
+    #           :activity_id => 50,
+    #            :created_at => Wed, 14 Feb 2024 13:21:13.964339000 UTC +00:00,
+    #            :updated_at => Wed, 14 Feb 2024 13:21:13.964339000 UTC +00:00
+    #   }
+    #
     def build_payloads
       build_primary_payload
       self.class.relations.each do |relation_config|
@@ -12,6 +31,9 @@ module LoggableActivity
       @payloads
     end
 
+    private
+
+    # Builds the primary payload.
     def build_primary_payload
       encrypted_attrs = encrypt_attrs(attributes, self.class.loggable_attrs, primary_encryption_key)
       @payloads << LoggableActivity::Payload.new(
@@ -22,6 +44,7 @@ module LoggableActivity
       )
     end
 
+    # Builds the payload for destroyed records.
     def build_destroy_payload
       encrypted_attrs = encrypt_attrs(attributes, self.class.loggable_attrs, primary_encryption_key)
       encrypted_attrs.transform_values! { '*** DELETED ***' }
@@ -33,6 +56,9 @@ module LoggableActivity
       )
     end
 
+    # Builds payloads for related records.
+    #
+    # @param relation_config [Hash] The configuration of the relation.
     def build_relation_payload(relation_config)
       relation_config.each_key do |key|
         case key
@@ -44,8 +70,12 @@ module LoggableActivity
       end
     end
 
-    def build_payload(relation_config, ralation_type)
-      associated_record = send(relation_config[ralation_type])
+    # Builds the payload for a specific relation.
+    #
+    # @param relation_config [Hash] The configuration of the relation.
+    # @param relation_type [String] The type of the relation.
+    def build_payload(relation_config, relation_type)
+      associated_record = send(relation_config[relation_type])
       return nil if associated_record.nil?
 
       associated_loggable_attrs = relation_config['loggable_attrs']
@@ -67,6 +97,11 @@ module LoggableActivity
       )
     end
 
+    # Retrieves the encryption key for the associated record.
+    #
+    # @param associated_record [ActiveRecord::Base] The associated record.
+    # @param data_owner [Boolean] Whether the associated record is the owner of the data.
+    # @return [LoggableActivity::EncryptionKey] The encryption key for the associated record.
     def associated_record_encryption_key(associated_record, data_owner)
       if data_owner
         LoggableActivity::EncryptionKey.for_record(associated_record, LoggableActivity::EncryptionKey.for_record(self))
@@ -75,11 +110,22 @@ module LoggableActivity
       end
     end
 
+    # Encrypts attributes.
+    #
+    # @param attrs [Hash] The attributes to be encrypted.
+    # @param loggable_attrs [Array<String>] The loggable attributes.
+    # @param encryption_key [String] The encryption key.
+    # @return [Hash] The encrypted attributes.
     def encrypt_attrs(attrs, loggable_attrs, encryption_key)
       attrs = attrs.slice(*loggable_attrs)
       encrypt_attr(attrs, encryption_key)
     end
 
+    # Encrypts a single attribute.
+    #
+    # @param attrs [Hash] The attributes to be encrypted.
+    # @param encryption_key [String] The encryption key.
+    # @return [Hash] The encrypted attributes.
     def encrypt_attr(attrs, encryption_key)
       attrs.each do |key, value|
         attrs[key] = LoggableActivity::Encryption.encrypt(value, encryption_key)

data/lib/loggable_activity/update_payloads_builder.rb

@@ -1,9 +1,69 @@
 # frozen_string_literal: true
 
-# This is a factory for building update payloads
-
 module LoggableActivity
+  # This module is responsible for building update payloads used in loggable activities.
   module UpdatePayloadsBuilder
+    # Builds payloads for an activity update event.
+    #
+    #  Example:
+    #    build_update_payloads
+    #
+    #   Returns:
+    #   [
+    #     [0] #<LoggableActivity::Payload:0x00000001047d31d8> {
+    #       :id => nil,
+    #       :record_type => "Demo::Club",
+    #       :record_id => 7,
+    #       :encrypted_attrs => {
+    #         "changes" => [
+    #           [0] {
+    #             "name" => {
+    #               "from" => "+aQznZK64KLQ8wsyZlSOGQbqm+J8gDX93rNFeF+wY68=\n",
+    #               "to" => "OdS834ZDS06+AYxmz4cUjhtgk7Jc8NoOVAAqR81Is7w=\n"
+    #             }
+    #           }
+    #         ]
+    #       },
+    #       :payload_type => "update_payload",
+    #       :data_owner => false,
+    #       :activity_id => nil,
+    #       :created_at => nil,
+    #       :updated_at => nil
+    #     },
+    #     [1] #<LoggableActivity::Payload:0x0000000107847f80> {
+    #       :id => nil,
+    #       :record_type => "Demo::Address",
+    #       :record_id => 7,
+    #       :encrypted_attrs => {
+    #         "street" => "W7cmT22Bb5TKVmtxTYJt1w==\n",
+    #         "city" => "AAwdTI7Xo86cMbFBAMsMIw==\n",
+    #         "country" => "7gu5wdu6O9tD7Q7+EDOqAg==\n",
+    #         "postal_code" => "ljjfT6MXGNK33/PUyi6Nmw==\n"
+    #       },
+    #       :payload_type => "previous_association",
+    #       :data_owner => false,
+    #       :activity_id => nil,
+    #       :created_at => nil,
+    #       :updated_at => nil
+    #     },
+    #     [2] #<LoggableActivity::Payload:0x0000000107802a98> {
+    #       :id => nil,
+    #       :record_type => "Demo::Address",
+    #       :record_id => 8,
+    #       :encrypted_attrs => {
+    #         "street" => "CuULVgIEgrOcWBxegKEvSg==\n",
+    #         "city" => "QbvodOYMvNFpkvsCprqGqg==\n",
+    #         "country" => "/N03d1OL3TY+aaiPUQ5N1A==\n",
+    #         "postal_code" => "ZZu3S5tnaTeq+wBu0dPKBw==\n"
+    #       },
+    #       :payload_type => "current_association",
+    #       :data_owner => false,
+    #       :activity_id => nil,
+    #       :created_at => nil,
+    #       :updated_at => nil
+    #     }
+    #   ]
+    #
     def build_update_payloads
       @update_payloads = []
 
@@ -16,6 +76,8 @@ module LoggableActivity
       @update_payloads
     end
 
+    private
+
     def primary_update_attrs
       previous_values = saved_changes.transform_values(&:first)
       current_values = saved_changes.transform_values(&:last)

data/lib/loggable_activity/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LoggableActivity
-  VERSION = '0.1.39'
+  VERSION = '0.1.40'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: loggable_activity
 version: !ruby/object:Gem::Version
-  version: 0.1.39
+  version: 0.1.40
 platform: ruby
 authors:
 - "Max \nGroenlund"
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-12 00:00:00.000000000 Z
+date: 2024-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -37,7 +37,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".DS_Store"
+- ".document"
+- ".nojekyll"
 - ".rspec"
 - ".rspec_status"
 - ".rubocop.yml"
@@ -49,6 +50,81 @@ files:
 - README.md
 - ROADMAP.md
 - Rakefile
+- doc/.nojekyll
+- doc/CHANGELOG_md.html
+- doc/CODE_OF_CONDUCT_md.html
+- doc/CONSIDERTIONS_md.html
+- doc/CreateLoggableActivities.html
+- doc/CreateLoggableEncryptionKeys.html
+- doc/CreateLoggablePayloads.html
+- doc/GETTING-STARTED_md.html
+- doc/Gemfile.html
+- doc/Gemfile_lock.html
+- doc/LICENSE_txt.html
+- doc/LoggableActivity/CurrentUser.html
+- doc/LoggableActivity/Generators.html
+- doc/LoggableActivity/Generators/InstallGenerator.html
+- doc/README_md.html
+- doc/ROADMAP_md.html
+- doc/Rakefile.html
+- doc/bin/setup.html
+- doc/notes/CHEAT_SHEET_md.html
+- doc/sig/loggable_activity_rbs.html
+- docs/LoggableActivity.html
+- docs/LoggableActivity/Activity.html
+- docs/LoggableActivity/Configuration.html
+- docs/LoggableActivity/Encryption.html
+- docs/LoggableActivity/EncryptionError.html
+- docs/LoggableActivity/EncryptionKey.html
+- docs/LoggableActivity/Error.html
+- docs/LoggableActivity/Hooks.html
+- docs/LoggableActivity/Payload.html
+- docs/LoggableActivity/PayloadsBuilder.html
+- docs/LoggableActivity/UpdatePayloadsBuilder.html
+- docs/created.rid
+- docs/css/fonts.css
+- docs/css/rdoc.css
+- docs/fonts/Lato-Light.ttf
+- docs/fonts/Lato-LightItalic.ttf
+- docs/fonts/Lato-Regular.ttf
+- docs/fonts/Lato-RegularItalic.ttf
+- docs/fonts/SourceCodePro-Bold.ttf
+- docs/fonts/SourceCodePro-Regular.ttf
+- docs/images/add.png
+- docs/images/arrow_up.png
+- docs/images/brick.png
+- docs/images/brick_link.png
+- docs/images/bug.png
+- docs/images/bullet_black.png
+- docs/images/bullet_toggle_minus.png
+- docs/images/bullet_toggle_plus.png
+- docs/images/date.png
+- docs/images/delete.png
+- docs/images/find.png
+- docs/images/loadingAnimation.gif
+- docs/images/macFFBgHack.png
+- docs/images/package.png
+- docs/images/page_green.png
+- docs/images/page_white_text.png
+- docs/images/page_white_width.png
+- docs/images/plugin.png
+- docs/images/ruby.png
+- docs/images/tag_blue.png
+- docs/images/tag_green.png
+- docs/images/transparent.png
+- docs/images/wrench.png
+- docs/images/wrench_orange.png
+- docs/images/zoom.png
+- docs/index.html
+- docs/js/darkfish.js
+- docs/js/navigation.js
+- docs/js/navigation.js.gz
+- docs/js/search.js
+- docs/js/search_index.js
+- docs/js/search_index.js.gz
+- docs/js/searcher.js
+- docs/js/searcher.js.gz
+- docs/table_of_contents.html
 - lib/.DS_Store
 - lib/generators/.DS_Store
 - lib/generators/loggable_activity/.DS_Store
@@ -59,6 +135,7 @@ files:
 - lib/generators/loggable_activity/templates/create_loggable_payloads.rb
 - lib/generators/loggable_activity/templates/current_user.rb
 - lib/generators/loggable_activity/templates/loggable_activity.en.yml
+- lib/generators/loggable_activity/templates/loggable_activity.yml
 - lib/loggable_activity.rb
 - lib/loggable_activity/.DS_Store
 - lib/loggable_activity/activity.rb
@@ -70,18 +147,13 @@ files:
 - lib/loggable_activity/payloads_builder.rb
 - lib/loggable_activity/update_payloads_builder.rb
 - lib/loggable_activity/version.rb
-- loggable_activity-0.1.32.gem
-- loggable_activity-0.1.33.gem
-- loggable_activity-0.1.34.gem
 - pkg/loggable_activity-0.1.35.gem
 - sig/loggable_activity.rbs
 homepage: https://loggableactivity-efe7b931c886.herokuapp.com/
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://loggableactivity-efe7b931c886.herokuapp.com/
-  source_code_uri: https://github.com/maxgronlund/LoggableActivity
-  changelog_uri: https://github.com/maxgronlund/LoggableActivity/CHANGELOG.md
+  documentation_uri: https://maxgronlund.github.io/LoggableActivity/
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []