rails-xapi 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f7f793c9d2d10b489f20f41d63f0687b2d38ad974792cd12600a98846634178
+  data.tar.gz: cd86c11505ed01f92f714949a1c34fd1ed12de12cc170e62409189b4885b3a77
+SHA512:
+  metadata.gz: 1b17754744f9266c1163bc1a38a1b48559b4e349de9d586216de28a097b904a4983f47c447895e4fe20040160d8779a21490dad14fe7eddde91a4b278c2d9668
+  data.tar.gz: d32ac593f6b50267cbfc491cd2e0a88cd79cb616f7d017f4822149ce50f851d0c74c9cf0c8a79ff4fc137c49f5741fee0e9a83c6e97d720909cf38fadec649a0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Hipjea
+
+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,152 @@
+# Rails xAPI
+
+This gem is a Rails engine that allows the validation of data from an xAPI statement. It enables the storage of xAPI statements in relational tables.
+
+[![Actions Status](https://github.com/fondation-unit/rails-xapi/actions/workflows/ci.yml/badge.svg)](https://github.com/fondation-unit/rails-xapi/actions/workflows/ci.yml/)
+
+> [!IMPORTANT]
+> This is an ongoing development. The documentation will be provided as it becomes available.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails-xapi", git: "https://github.com/fondation-unit/rails-xapi"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Create the migration files:
+
+```bash
+$ bin/rails rails_xapi:install:migrations
+```
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+mount RailsXapi::Engine, at: "rails-xapi"
+```
+
+## Usage
+
+### Statement creation
+
+Example usage of the `RailsXapi::StatementCreator` service:
+
+```ruby
+user_name = "#{user.firstname} #{user.lastname}"
+
+data = {
+  actor: {
+    objectType: "Agent",
+    name: user_name,
+    mbox: "mailto:#{user.email}",
+    account: {
+      homePage: "http://example.com/some_user_homepage/#{user&.id}",
+      name: user_name
+    }
+  },
+  verb: {
+    id: "https://brindlewaye.com/xAPITerms/verbs/loggedin/"
+  },
+  object: {
+    id: new_user_session_url,
+    definition: {
+      name: {
+        "en-US" => "log in"
+      },
+      description: {
+        "en-US" => "User signed in"
+      }
+    }
+  }
+}
+
+RailsXapi::StatementCreator.create(data)
+```
+
+### Data query
+
+Ready-to-use queries are available in the [app/services/rails_xapi/query.rb](app/services/rails_xapi/query.rb) class.
+
+| Query symbol                       | Description                                               |
+| ---------------------------------- | --------------------------------------------------------- |
+| `:statement`                       | Retrieve a single statement by its ID                     |
+| `:statements_by_object_and_actors` | Get statements by object IDand actor emails               |
+| `:verb_ids`                        | Get list of unique verb IDs                               |
+| `:verb_displays`                   | Get list of unique verb display values                    |
+| `:verbs`                           | Get hash of unique verbs with ID and display values       |
+| `:actor_by_email`                  | Find statements by actor's email                          |
+| `:actor_by_mbox`                   | Find statements by actor's mbox                           |
+| `:actor_by_account_homepage`       | Find statements by actor's account homepage               |
+| `:actor_by_openid`                 | Find statements by actor's openID                         |
+| `:actor_by_mbox_sha1sum`           | Find statements by actor's mbox SHA1 sum                  |
+| `:user_statements_per_month`       | Retrieve actor's statements for a specific month/year     |
+| `:per_month`                       | Group given records by creation date for a specific month |
+| `:month_graph_data`                | Create date/count array of data for a month               |
+
+Example of usage:
+
+```ruby
+def create_statement
+  data = {
+    actor: {
+      objectType: "Agent",
+      name: "John Doe",
+      mbox: "mailto:example@localhost.com",
+      account: {
+        homePage: "http://example.com/some_user_homepage/1",
+        name: "JohnDoe#1"
+      }
+    },
+    verb: {
+      id: "https://brindlewaye.com/xAPITerms/verbs/loggedin/"
+    },
+    object: {
+      id: "http://localhost:3000/new_user_session",
+      definition: {
+        name: {
+          "en-GB" => "login"
+        },
+        description: {
+          "en-US" => "User signed in."
+        }
+      }
+    }
+  }
+
+  statement = RailsXapi::StatementCreator.create(data)
+  redirect_to statement_show_path(id: statement[:statement][:id])
+end
+
+def statement_show
+  @statement = RailsXapi::Query.call(
+    query: :statement,
+    args: params[:id]
+  )
+end
+
+def logs_per_month(year = Date.current.year, month = Date.current.month)
+  RailsXapi::Query.call(
+    query: :user_statements_per_month,
+    args: [{mbox: "mailto:#{email}"}, year, month]
+  )
+end
+```
+
+## Test
+
+```bash
+bundle exec rails db:schema:load RAILS_ENV=test
+bundle exec rspec spec/
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/rails_xapi/application_controller.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RailsXapi
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+  end
+end

data/app/helpers/rails_xapi/application_helper.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RailsXapi
+  module ApplicationHelper
+    # Output the duration ISO 8601 in minutes.
+    def duration_to_minutes(duration)
+      sprintf("%.2f", ActiveSupport::Duration.parse(duration)&.in_minutes)
+    end
+
+    # Output the value of a JSON row in a specific locale.
+    def json_value_for_locale(json_str, locale = I18n.locale)
+      hash = JSON.parse(json_str)
+      result = hash.select { |key, _value| key.include?(locale.to_s) }
+      result.values.first.to_s || hash.first.value.to_s
+    rescue
+      json_str
+    end
+
+    # Output the result score as a percentage.
+    def result_success_rate(result)
+      return nil if result.score_raw.blank? || result.score_max.blank?
+
+      ((result.score_raw.to_f / result.score_max.to_f) * 100).to_i
+    end
+  end
+end

data/app/jobs/rails_xapi/application_job.rb

@@ -0,0 +1,4 @@
+module RailsXapi
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/rails_xapi/create_statement_job.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class RailsXapi::CreateStatementJob < ApplicationJob
+  queue_as :default
+
+  def perform(statement)
+    statement.save if statement.present?
+
+    { status: 200, statement: statement }
+  end
+end

data/app/mailers/rails_xapi/application_mailer.rb

@@ -0,0 +1,6 @@
+module RailsXapi
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/concerns/serializable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Serializable
+  extend ActiveSupport::Concern
+
+  LATIN_LETTERS = "a-zA-ZÀ-ÖØ-öø-ÿœ"
+  LATIN_LETTERS_REGEX = /[^#{LATIN_LETTERS}\s-]/i
+
+  included do
+    def serialized_value(data)
+      data.is_a?(Hash) ? data.to_json : data.to_s
+    end
+  end
+end

data/app/models/rails_xapi/account.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Represents an account with home_page and name.
+class RailsXapi::Account < ApplicationRecord
+  require "uri"
+
+  belongs_to :actor, class_name: "RailsXapi::Actor", dependent: :destroy
+
+  def homePage=(value)
+    # We need to match the camel case notation from JSON data.
+    self.home_page = value
+  end
+end
+
+# == Schema Information
+#
+# Table name: rails_xapi_accounts
+#
+#  id        :integer          not null, primary key
+#  home_page :string           not null
+#  name      :string           not null
+#  actor_id  :bigint           not null
+#
+# Indexes
+#
+#  index_rails_xapi_accounts_on_actor_id  (actor_id)
+#

data/app/models/rails_xapi/activity_definition.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+# The object optional activity definition.
+# See: https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#activity-definition
+class RailsXapi::ActivityDefinition < ApplicationRecord
+  include Serializable
+  include RailsXapi::ApplicationHelper
+
+  belongs_to :object, class_name: "RailsXapi::Object"
+  has_one :interaction_activity,
+          class_name: "RailsXapi::InteractionActivity",
+          dependent: :destroy
+  has_many :extensions, as: :extendable, dependent: :destroy
+
+  validates :activity_type,
+            format: {
+              with: %r{\A\w+://\S+\z},
+              message: I18n.t("rails_xapi.errors.must_be_a_valid_iri")
+            },
+            allow_blank: true
+
+  before_validation :set_name, :set_description
+  validates_with RailsXapi::Validators::LanguageMapValidator,
+                 attributes: %i[name description]
+
+  def type
+    # Virtual attribute to bypass the Single Table Inheritance keyword.
+    activity_type
+  end
+
+  def type=(value)
+    # Store the `type` attribute into `activity_type` column to avoid
+    # reserved key-words issues.
+    self.activity_type = value
+  end
+
+  def moreInfo=(value)
+    # Match the camel case notation from JSON data.
+    self.more_info = value
+  end
+
+  def assign_from_json_definition(definition_hash)
+    return unless definition_hash.present?
+
+    normalized_hash = definition_hash.deep_stringify_keys
+    interaction_keys = RailsXapi::InteractionActivity::INTERACTION_KEYS
+
+    interaction_attrs = normalized_hash.slice(*interaction_keys)
+    core_attrs = normalized_hash.except(*interaction_keys)
+    # Assign base definition attributes
+    self.attributes = core_attrs
+
+    if normalized_hash["interactionType"].present?
+      # Assign InteractionActivity attributes
+      build_interaction_activity unless interaction_activity
+
+      interaction_activity.interaction_type =
+        interaction_attrs["interactionType"]
+      interaction_activity.correct_responses_pattern =
+        interaction_attrs["correctResponsesPattern"]
+      # Build the interaction_components association
+      interaction_activity.assign_interaction_components(interaction_attrs)
+
+      # Trigger the validation
+      unless interaction_activity.valid?
+        raise ActiveRecord::RecordInvalid, interaction_activity
+      end
+
+      interaction_activity.save!
+    end
+  end
+
+  def extensions=(extensions_data)
+    unless extensions_data.is_a?(Hash)
+      raise RailsXapi::Errors::XapiError,
+            I18n.t(
+              "rails_xapi.errors.attribute_must_be_a_hash",
+              name: "extensions"
+            )
+    end
+
+    # Find any existing extension for the given activity definition.
+    exts = extensions.where(extendable_type: self.class.to_s, extendable_id: id)
+
+    # If none, build and save the extensions.
+    if exts.blank?
+      extensions_data.each do |iri, data|
+        extensions.build(iri: iri, value: serialized_value(data))
+      end
+    end
+  end
+
+  def as_json
+    { name: name, description: description, type: activity_type }.tap do |hash|
+      hash[:extensions] = extensions.as_json if extensions.present?
+      hash[:moreInfo] = more_info if more_info.present?
+      hash.merge!(interaction_activity.as_json) if interaction_activity.present?
+    end
+  end
+
+  private
+
+  def set_json_attribute(attribute)
+    value = send(attribute)
+    return if value.blank?
+
+    begin
+      value = JSON.parse(value.to_s.gsub("=>", ":"))
+    rescue JSON::ParserError => _
+      raise RailsXapi::Errors::XapiError,
+            I18n.t(
+              "rails_xapi.errors.attribute_must_be_a_valid_language_map",
+              name: attribute
+            )
+    end
+
+    self[attribute] = value.to_json
+  end
+
+  def set_name
+    set_json_attribute(:name)
+  end
+
+  def set_description
+    set_json_attribute(:description)
+  end
+end
+
+# == Schema Information
+#
+# Table name: rails_xapi_activity_definitions
+#
+#  id            :integer          not null, primary key
+#  activity_type :string
+#  description   :text
+#  more_info     :text
+#  name          :string
+#  object_id     :string           not null
+#
+# Indexes
+#
+#  index_rails_xapi_activity_definitions_on_object_id  (object_id)
+#

data/app/models/rails_xapi/actor.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+# The Actor defines who performed the action.
+# See: https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#242-actor
+class RailsXapi::Actor < ApplicationRecord
+  require "uri"
+  include Serializable
+
+  OBJECT_TYPES = %w[Agent Group]
+
+  attr_accessor :objectType, :member
+
+  has_one :account, class_name: "RailsXapi::Account", dependent: :destroy
+  has_many :statements, class_name: "RailsXapi::Statement", dependent: :nullify
+  has_many :members, class_name: "RailsXapi::GroupMember", dependent: :destroy
+
+  validates :object_type, presence: true
+  validate :validate_actor_ifi_presence,
+           :validate_mbox,
+           :validate_mbox_sha1sum,
+           :validate_object_type,
+           :validate_openid
+
+  after_initialize :set_defaults
+  before_validation :normalize_actor
+  after_commit :create_members, if: :is_group?
+
+  # Build the Actor object from the given data and user email.
+  #
+  # @param [Hash] data The data used to build the actor object, including optional nested account data.
+  # @return [RailsXapi::Actor] The actor object initialized with the data.
+  def self.build_actor_from_data(data)
+    data = handle_account_data(data)
+
+    conditions = data.slice(:mbox, :mbox_sha1sum, :openid).compact
+    find_by(conditions) || create(data)
+  end
+
+  # Find an Actor by its identifiers or create a new one.
+  #
+  # @param [Hash] data The data to find or create the actor.
+  # @return [RailsXapi::Actor] The found or created actor object.
+  def self.by_iri_or_create(data)
+    data = handle_account_data(data)
+
+    actor =
+      find_or_create_by(
+        mbox: data[:mbox],
+        mbox_sha1sum: data[:mbox_sha1sum],
+        openid: data[:openid]
+      ) { |a| a.attributes = data }
+
+    unless actor.valid?
+      raise RailsXapi::Errors::XapiError,
+            I18n.t("rails_xapi.errors.invalid_actor")
+    end
+
+    actor
+  end
+
+  def validate_mbox
+    return if mbox.blank?
+
+    mbox_valid =
+      mbox.strip =~ /\Amailto:([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/
+    unless mbox_valid
+      raise RailsXapi::Errors::XapiError,
+            I18n.t("rails_xapi.errors.malformed_mbox", name: mbox)
+    end
+
+    true
+  end
+
+  # Overrides the Hash class method to camelize object_type, according to the xAPI specification.
+  # See: https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#part-two-experience-api-data
+  #
+  # @return [Hash] The actor hash with the camel-case version of object_type.
+  def as_json
+    {
+      objectType: object_type,
+      name: name,
+      mbox: mbox,
+      mbox_sha1sum: mbox_sha1sum,
+      account: account.as_json,
+      openid: openid
+    }.compact
+  end
+
+  private
+
+  def set_defaults
+    # We need to match the camel case notation from JSON data.
+    self.object_type =
+      objectType.presence || object_type.presence || OBJECT_TYPES.first
+    self.member = member.presence || nil
+  end
+
+  def is_group?
+    object_type === "Group"
+  end
+
+  # Normalizes the actor data.
+  #
+  # @param [Hash] actor The actor data.
+  # @return [Hash] The normalized actor data.
+  def normalize_actor
+    self.object_type = object_type.presence || OBJECT_TYPES.first
+
+    if name.present?
+      self.name =
+        name
+          .gsub(Serializable::LATIN_LETTERS_REGEX, "")
+          .to_s
+          .humanize
+          .gsub(/\b('?[#{Serializable::LATIN_LETTERS}])/o) do
+            Regexp.last_match(1).capitalize
+          end
+    end
+
+    self.mbox = mbox.strip.downcase if mbox.present?
+  end
+
+  # Find an Account by its identifier or create a new one and set the actor's data.
+  #
+  # @param [Hash] data The data to find or create the account.
+  # @return [Hash] The actor's data.
+  private_class_method def self.handle_account_data(data)
+    if (account_data = data[:account]).present?
+      account =
+        RailsXapi::Account.find_or_create_by(
+          home_page: account_data[:homePage]
+        ) { |a| a.name = account_data[:name] }
+
+      data[:account] = account
+      data[:name] ||= account_data[:name]
+    end
+
+    data
+  end
+
+  def validate_actor_ifi_presence
+    unless mbox.present? || mbox_sha1sum.present? || openid.present? ||
+             account.present?
+      raise RailsXapi::Errors::XapiError,
+            I18n.t("rails_xapi.errors.actor_ifi_must_be_present")
+    end
+  end
+
+  def validate_mbox_sha1sum
+    return if mbox_sha1sum.blank?
+
+    unless is_sha1?(mbox_sha1sum)
+      raise RailsXapi::Errors::XapiError,
+            I18n.t("rails_xapi.errors.malformed_mbox_sha1sum")
+    end
+
+    true
+  end
+
+  def validate_object_type
+    object_type_valid = OBJECT_TYPES.include?(object_type)
+    unless object_type_valid
+      raise RailsXapi::Errors::XapiError,
+            I18n.t(
+              "rails_xapi.errors.invalid_actor_object_type",
+              name: object_type
+            )
+    end
+
+    true
+  end
+
+  def validate_openid
+    return if openid.blank?
+
+    uri = URI.parse(openid)
+    is_valid_openid_uri = uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+    unless is_valid_openid_uri
+      raise RailsXapi::Errors::XapiError,
+            I18n.t("rails_xapi.errors.malformed_openid_uri", uri: openid)
+    end
+
+    true
+  end
+
+  # Produces the hex-encoded SHA1 hash of the actor mailto.
+  #
+  # @param [String] mbox The mbox clear value to be encoded.
+  # @return [Boolean] True if the value is matching, false otherwise.
+  def is_sha1?(str)
+    # SHA-1 hash is a 40-character hexadecimal string consisting of numbers 0-9 and letters a-f.
+    # We also handle the case with an optional "sha1" prefix.
+    !!(str =~ /^(sha1:)?[0-9a-f]{40}$/i)
+  end
+
+  # Create members in the case of a "Group" objectType.
+  def create_members
+    # We should end the function here when we create a group without members (ex: a team in the context object).
+    return if member.blank?
+
+    if id.blank?
+      raise RailsXapi::Errors::XapiError,
+            I18n.t("rails_xapi.errors.failed_to_create_group_members")
+    end
+
+    member.each do |m|
+      new_actor = RailsXapi::Actor.by_iri_or_create(m)
+      RailsXapi::GroupMember.create(group_id: id, actor_id: new_actor.id)
+    rescue => _
+      raise RailsXapi::Errors::XapiError,
+            I18n.t("rails_xapi.errors.failed_to_create_member", member: m)
+    end
+  end
+end
+
+# == Schema Information
+#
+# Table name: rails_xapi_actors
+#
+#  id           :integer          not null, primary key
+#  mbox         :string
+#  mbox_sha1sum :string
+#  name         :string
+#  object_type  :string
+#  openid       :string
+#  created_at   :datetime         not null
+#

data/app/models/rails_xapi/application_record.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class RailsXapi::ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+end