notificare 0.1.0.alpha.1

data/lib/generators/active_job/notificare/install/install_generator.rb

@@ -0,0 +1,56 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActiveJob
+  module Notificare
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        include Rails::Generators::Migration
+
+        source_root File.expand_path("templates", __dir__)
+
+        def self.next_migration_number(dirname)
+          ActiveRecord::Generators::Base.next_migration_number(dirname)
+        end
+
+        def create_migration_file
+          migration_template(
+            "create_active_job_notificare_tables.rb.tt",
+            "db/migrate/create_active_job_notificare_tables.rb"
+          )
+        end
+
+        def create_initializer
+          template "initializer.rb.tt", "config/initializers/active_job_notificare.rb"
+        end
+
+        def append_route_comment
+          route "# mount ActiveJob::Notificare::Engine => \"/notificare\""
+        end
+
+        def create_view_partials
+          template "_progress.html.erb.tt", "app/views/active_job/notificare/_progress.html.erb"
+          template "_notifications.html.erb.tt", "app/views/active_job/notificare/_notifications.html.erb"
+          template "_notification.html.erb.tt", "app/views/active_job/notificare/_notification.html.erb"
+        end
+
+        private
+
+        def json_column_type
+          case ActiveRecord::Base.connection.adapter_name.downcase
+          when /postgresql/, /postgis/
+            "jsonb"
+          when /mysql/
+            "json"
+          else
+            "text"
+          end
+        end
+
+        def migration_version
+          "[#{ActiveRecord::Migration.current_version}]"
+        end
+      end
+    end
+  end
+end

data/lib/generators/active_job/notificare/install/templates/_notification.html.erb.tt

@@ -0,0 +1,19 @@
+<%%= turbo_frame_tag dom_id(notification) do %>
+  <div class="notificare-notification<%%= notification.read? ? "" : " notificare-notification--unread" %>">
+    <strong class="notificare-notification__title"><%%= notification.title %></strong>
+    <%% if notification.description.present? %>
+      <p class="notificare-notification__description"><%%= notification.description %></p>
+    <%% end %>
+    <div class="notificare-notification__actions">
+      <%% unless notification.read? %>
+        <%%= button_to t("active_job.notificare.notifications.mark_as_read"), notificare.read_notification_path(notification), method: :patch %>
+      <%% end %>
+      <%%= button_to t("active_job.notificare.notifications.dismiss"), notificare.dismiss_notification_path(notification), method: :patch %>
+      <%% if notification.actions.present? %>
+        <%% notification.actions.each do |action| %>
+          <%%= link_to action["label"], action["url"] %>
+        <%% end %>
+      <%% end %>
+    </div>
+  </div>
+<%% end %>

data/lib/generators/active_job/notificare/install/templates/_notifications.html.erb.tt

@@ -0,0 +1,7 @@
+<%%= turbo_stream_from "active_job_notifications", recipient.to_gid_param %>
+<div id="active_job_notifications" class="notificare-inbox">
+  <%%= button_to t(".clear_all"), notificare.clear_notifications_path, method: :delete %>
+  <%% notifications.each do |notification| %>
+    <%%= render "active_job/notificare/notification", notification: notification %>
+  <%% end %>
+</div>

data/lib/generators/active_job/notificare/install/templates/_progress.html.erb.tt

@@ -0,0 +1,17 @@
+<%%= turbo_stream_from "active_job_progress", execution.job_id %>
+<div id="<%%= dom_id(execution) %>" class="notificare-progress">
+  <%% if execution.progress_total.present? %>
+    <progress class="notificare-progress__bar" value="<%%= execution.progress_current %>" max="<%%= execution.progress_total %>"></progress>
+    <span class="notificare-progress__label"><%%= execution.progress_current %>/<%%= execution.progress_total %> (<%%= (execution.progress_current.to_f / execution.progress_total * 100).round %>%)</span>
+    <%% if execution.current_step.present? %>
+      <span class="notificare-progress__step"><%%= execution.current_step %></span>
+    <%% end %>
+  <%% else %>
+    <%% if !execution.failed? %>
+      <span class="notificare-progress__spinner" role="status" aria-label="Loading..."></span>
+    <%% end %>
+    <%% if execution.current_step.present? %>
+      <span class="notificare-progress__step"><%%= execution.current_step %></span>
+    <%% end %>
+  <%% end %>
+</div>

data/lib/generators/active_job/notificare/install/templates/create_active_job_notificare_tables.rb.tt

@@ -0,0 +1,36 @@
+class CreateActiveJobNotificareTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :active_job_executions do |t|
+      t.string :job_id, null: false
+      t.string :job_class, null: false
+      t.string :status, null: false, default: "enqueued"
+      t.string :current_step
+      t.integer :progress_current, null: false, default: 0
+      t.integer :progress_total
+      t.datetime :started_at
+      t.datetime :completed_at
+      t.text :error
+      t.timestamps
+    end
+
+    add_index :active_job_executions, :job_id, unique: true
+    add_index :active_job_executions, :job_class
+
+    create_table :active_job_notifications do |t|
+      t.string :recipient_type, null: false
+      t.string :recipient_id, null: false
+      t.string :job_id
+      t.string :event_type, null: false
+      t.string :title, null: false
+      t.text :description
+      t.<%= json_column_type %> :metadata
+      t.<%= json_column_type %> :actions
+      t.datetime :read_at
+      t.datetime :dismissed_at
+      t.timestamps
+    end
+
+    add_index :active_job_notifications, :recipient_id
+    add_index :active_job_notifications, :job_id
+  end
+end

data/lib/generators/active_job/notificare/install/templates/initializer.rb.tt

@@ -0,0 +1,24 @@
+# ActiveJob::Notificare configuration
+#
+# Generated by: rails generate active_job:notificare:install
+#
+# Notificare is a projection layer over ActiveJob::Continuation. Including
+# `ActiveJob::Notificare` in a job pulls in Continuation, the step DSL, and the
+# notification primitives.
+#
+# ActiveJob::Notificare.configure do |config|
+#   # How long to retain completed and failed execution records.
+#   # Default: 7.days — Set to nil to keep indefinitely.
+#   # config.execution_retention = 7.days
+#
+#   # Broadcast real-time progress updates via Turbo Streams.
+#   # Requires Action Cable to be configured in your application.
+#   # config.broadcast_progress = true
+#
+#   # Broadcast real-time notification updates via Turbo Streams.
+#   # config.broadcast_notifications = true
+#
+#   # Mount path for the engine admin UI.
+#   # Default: "/notificare"
+#   # config.mount_path = "/notificare"
+# end

data/lib/generators/active_job/notificare/scaffold/scaffold_generator.rb

@@ -0,0 +1,74 @@
+require "rails/generators"
+
+module ActiveJob
+  module Notificare
+    module Generators
+      class ScaffoldGenerator < Rails::Generators::NamedBase
+        source_root File.expand_path("templates", __dir__)
+
+        class_option :controller, type: :string,
+          desc: "Override the controller class name (e.g. --controller=MyImportsController)"
+        class_option :prefix, type: :string,
+          desc: "Override the route and view directory prefix (e.g. --prefix=my_imports)"
+
+        def validate_job_class
+          klass = class_name.constantize
+          unless klass.ancestors.include?(::ActiveJob::Notificare)
+            say_status :error,
+              "#{class_name} does not include ActiveJob::Notificare. " \
+              "Add `include ActiveJob::Notificare` to the job class and re-run the generator.",
+              :red
+            @invalid = true
+          end
+        rescue NameError
+          say_status :error,
+            "#{class_name} could not be loaded. " \
+            "Make sure the job class exists and includes `include ActiveJob::Notificare`.",
+            :red
+          @invalid = true
+        end
+
+        def create_controller
+          return if @invalid
+          template "controller.rb.tt", "app/controllers/#{prefix}_controller.rb"
+        end
+
+        def create_views
+          return if @invalid
+          template "index.html.erb.tt", "app/views/#{prefix}/index.html.erb"
+          template "show.html.erb.tt", "app/views/#{prefix}/show.html.erb"
+        end
+
+        def create_locale
+          return if @invalid
+          template "locale.en.yml.tt", "config/locales/active_job_notificare_#{prefix}.en.yml"
+        end
+
+        def print_routes_snippet
+          return if @invalid
+          say "\nPaste into config/routes.rb:\n\n"
+          say "  resources :#{prefix}, only: [:index, :show]", :green
+          say ""
+        end
+
+        private
+
+        def resource_name
+          file_name.sub(/_job$/, "")
+        end
+
+        def plural_resource_name
+          resource_name.pluralize
+        end
+
+        def prefix
+          options[:prefix] || plural_resource_name
+        end
+
+        def scaffold_controller_class_name
+          options[:controller] || "#{plural_resource_name.camelize}Controller"
+        end
+      end
+    end
+  end
+end

data/lib/generators/active_job/notificare/scaffold/templates/controller.rb.tt

@@ -0,0 +1,31 @@
+class <%= scaffold_controller_class_name %> < ApplicationController
+  def index
+    # Scope executions to job runs that produced at least one notification for this recipient.
+    job_ids = ActiveJob::Notificare::Notification
+      .where(recipient: current_recipient)
+      .select(:job_id)
+      .distinct
+    @executions = ActiveJob::Notificare::Execution
+      .where(job_class: "<%= class_name %>", job_id: job_ids)
+      .recent
+  end
+
+  def show
+    @execution = ActiveJob::Notificare::Execution
+      .where(job_class: "<%= class_name %>")
+      .find(params[:id])
+    @notifications = ActiveJob::Notificare::Notification
+      .where(recipient: current_recipient, job_id: @execution.job_id)
+      .visible
+  rescue ActiveRecord::RecordNotFound
+    head :not_found
+  end
+
+  private
+
+  # TODO: replace with however your app exposes the signed-in user/account.
+  def current_recipient
+    current_notificare_recipient || current_user
+  end
+  helper_method :current_recipient
+end

data/lib/generators/active_job/notificare/scaffold/templates/index.html.erb.tt

@@ -0,0 +1,26 @@
+<%# Subscribes this page to live notification updates for the current user.
+    New notifications arrive as Turbo Stream broadcasts without a page reload. %>
+<%%= turbo_stream_from "active_job_notifications", current_recipient.to_gid_param %>
+
+<h1><%%= t(".title") %></h1>
+
+<%% if @executions.any? %>
+  <%% @executions.each do |execution| %>
+    <div>
+      <%%= active_job_notificare(execution) %>
+      <p>
+        <%%= t(".status_label") %>: <%%= execution.status %>
+        <%% if execution.started_at %>
+          &mdash; <%%= t(".started_label") %>: <%%= execution.started_at.strftime("%Y-%m-%d %H:%M") %>
+        <%% end %>
+      </p>
+      <%%= link_to t(".details"), <%= resource_name %>_path(execution) %>
+    </div>
+  <%% end %>
+<%% else %>
+  <p><%%= t(".empty") %></p>
+<%% end %>
+
+<%# Renders the recipient's notification inbox with live updates and
+    inline Mark-as-read / Dismiss actions via Turbo Streams. %>
+<%%= active_job_notifications(for: current_recipient) %>

data/lib/generators/active_job/notificare/scaffold/templates/locale.en.yml.tt

@@ -0,0 +1,18 @@
+en:
+  <%= prefix %>:
+    index:
+      title: "<%= plural_resource_name.titleize %>"
+      empty: "No <%= plural_resource_name.humanize.downcase %> found."
+      status_label: "Status"
+      started_label: "Started"
+      details: "Details"
+    show:
+      back: "← <%= plural_resource_name.titleize %>"
+      title: "<%= resource_name.humanize %> details"
+      status_label: "Status"
+      started_label: "Started"
+      completed_label: "Completed"
+      error_label: "Error"
+      progress_heading: "Progress"
+      notifications_heading: "Notifications"
+      no_notifications: "No notifications for this run yet."

data/lib/generators/active_job/notificare/scaffold/templates/show.html.erb.tt

@@ -0,0 +1,39 @@
+<%%= link_to t(".back"), <%= prefix %>_path %>
+
+<h1><%%= t(".title") %></h1>
+<p class="job-id"><%%= @execution.job_id %></p>
+
+<dl>
+  <dt><%%= t(".status_label") %></dt>
+  <dd><%%= @execution.status %></dd>
+
+  <dt><%%= t(".started_label") %></dt>
+  <dd><%%= @execution.started_at&.strftime("%Y-%m-%d %H:%M:%S") || "—" %></dd>
+
+  <dt><%%= t(".completed_label") %></dt>
+  <dd><%%= @execution.completed_at&.strftime("%Y-%m-%d %H:%M:%S") || "—" %></dd>
+
+  <%% if @execution.error.present? %>
+    <dt><%%= t(".error_label") %></dt>
+    <dd><%%= @execution.error %></dd>
+  <%% end %>
+</dl>
+
+<%# Live progress widget. Subscribes to turbo_stream "active_job_progress", job_id — the
+    progress bar / spinner updates automatically while the job is running. %>
+<h2><%%= t(".progress_heading") %></h2>
+<%%= active_job_notificare(@execution) %>
+
+<%# Per-run notification list. Subscribes to the recipient's notification stream so new
+    notifications for this job run appear without a page reload. %>
+<h2><%%= t(".notifications_heading") %></h2>
+<%%= turbo_stream_from "active_job_notifications", current_recipient.to_gid_param %>
+<div id="<%%= dom_id(@execution, :notifications) %>">
+  <%% if @notifications.any? %>
+    <%% @notifications.each do |notification| %>
+      <%%= render "active_job/notificare/notification", notification: notification %>
+    <%% end %>
+  <%% else %>
+    <p><%%= t(".no_notifications") %></p>
+  <%% end %>
+</div>

data/lib/notificare.rb

@@ -0,0 +1,4 @@
+require "active_job/notificare"
+
+module Notificare
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: notificare
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha.1
+platform: ruby
+authors:
+- Gabriel Quaresma
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+description: 'Notificare (Romanian: ''to notify'') is a Rails engine built on top
+  of ActiveJob::Continuation. It adds a persisted projection of running-job progress,
+  a durable user-facing notification inbox, and a Hotwire UI scaffold — turning Continuation''s
+  resumable steps into a state machine that drives notifications without manual broadcast
+  plumbing.'
+email:
+- j.quaresmasantos_98@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- app/assets/stylesheets/active_job/notificare/engine.css
+- app/controllers/active_job/notificare/application_controller.rb
+- app/controllers/active_job/notificare/executions_controller.rb
+- app/controllers/active_job/notificare/notifications_controller.rb
+- app/helpers/active_job/notificare/view_helpers.rb
+- app/models/active_job/notificare/application_record.rb
+- app/models/active_job/notificare/execution.rb
+- app/models/active_job/notificare/notification.rb
+- app/views/active_job/notificare/_notification.html.erb
+- app/views/active_job/notificare/_notifications.html.erb
+- app/views/active_job/notificare/_progress.html.erb
+- app/views/active_job/notificare/executions/index.html.erb
+- app/views/active_job/notificare/executions/show.html.erb
+- app/views/active_job/notificare/notifications/clear.turbo_stream.erb
+- app/views/active_job/notificare/notifications/dismiss.turbo_stream.erb
+- app/views/active_job/notificare/notifications/read.turbo_stream.erb
+- app/views/layouts/active_job/notificare/application.html.erb
+- config/locales/en.yml
+- config/routes.rb
+- lib/active_job/notificare.rb
+- lib/active_job/notificare/concern.rb
+- lib/active_job/notificare/engine.rb
+- lib/active_job/notificare/progress_handle.rb
+- lib/active_job/notificare/projection.rb
+- lib/active_job/notificare/recipient.rb
+- lib/active_job/notificare/step_dsl.rb
+- lib/active_job/notificare/version.rb
+- lib/generators/active_job/notificare/install/install_generator.rb
+- lib/generators/active_job/notificare/install/templates/_notification.html.erb.tt
+- lib/generators/active_job/notificare/install/templates/_notifications.html.erb.tt
+- lib/generators/active_job/notificare/install/templates/_progress.html.erb.tt
+- lib/generators/active_job/notificare/install/templates/create_active_job_notificare_tables.rb.tt
+- lib/generators/active_job/notificare/install/templates/initializer.rb.tt
+- lib/generators/active_job/notificare/scaffold/scaffold_generator.rb
+- lib/generators/active_job/notificare/scaffold/templates/controller.rb.tt
+- lib/generators/active_job/notificare/scaffold/templates/index.html.erb.tt
+- lib/generators/active_job/notificare/scaffold/templates/locale.en.yml.tt
+- lib/generators/active_job/notificare/scaffold/templates/show.html.erb.tt
+- lib/notificare.rb
+homepage: https://github.com/joaoGabriel55/notificare
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/joaoGabriel55/notificare
+  source_code_uri: https://github.com/joaoGabriel55/notificare
+  changelog_uri: https://github.com/joaoGabriel55/notificare/blob/v0.1.0.alpha.1/CHANGELOG.md
+  bug_tracker_uri: https://github.com/joaoGabriel55/notificare/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.5'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Progress tracking and notification inbox for ActiveJob::Continuation
+test_files: []