convo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3416a31cc10bcf8ed359acdf7d4944406aab4517fb2bbdefb072994991596c30
+  data.tar.gz: 02746a993546ab98e41cc6263816f0e30e5eec6176a82f93f68f53438208528d
+SHA512:
+  metadata.gz: 0cb462b86cee06311d65dada1896f98de3beb64671a2cd471f73d41b5b0adfaeba4a18a7683cba239eb6545a972471b50d3ad9da6b416a5d927c0af5574627e8
+  data.tar.gz: 8c7e6875855a9a65c42ee4bc56c7826dd9414b299c1961d821937fda5eea872df955bb28d6f81110db88092d08aec9ddc0574ef8470322cb0f8f1ad98296d40c

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Ben
+
+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,156 @@
+# Convo
+
+[![Gem Version](https://badge.fury.io/rb/convo.svg)](https://badge.fury.io/rb/convo)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Convo is a Rails engine that provides a flexible and customizable conversation system for your Rails application. It enables easy implementation of messaging and conversation features between users of your application.
+
+## Features
+
+- Easy-to-use conversation system
+- Support for multiple participants in conversations
+- Automatic conversation threading and topic management
+- Model-agnostic implementation (works with any user model)
+- Built-in validations and security measures
+- Clean and simple API
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'convo'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install convo
+```
+
+## Setup
+
+1. Install the migrations:
+
+```bash
+$ rails convo:install:migrations
+$ rails db:migrate
+```
+
+2. Include the `HasConvo` module in your user model:
+
+```ruby
+class User < ApplicationRecord
+  include Convo::HasConvo
+end
+```
+
+## Usage
+
+### Starting a Conversation
+
+To send a message to one or multiple recipients:
+
+```ruby
+# Send to a single recipient
+user.send_message(
+  recipients: recipient,
+  body: "Hello!"
+)
+
+# Send to multiple recipients
+user.send_message(
+  recipients: [recipient1, recipient2],
+  body: "Hello everyone!"
+)
+```
+
+### Accessing Conversations
+
+```ruby
+# Get all topics for a user
+user.topics
+
+# Get all messages for a user
+user.messages
+
+# Get messages from a specific topic
+topic.messages
+```
+
+### Understanding Topics
+
+Topics are unique per combination of participants. For example:
+
+- If a topic exists between User1 and User2
+- And you send a message to User1, User2, and User3
+- A new topic will be created for this three-person conversation
+- The original topic between User1 and User2 remains separate
+
+This ensures that conversations between different groups of participants stay organized and separate, even if there's overlap in the participants.
+
+### Context and Tenant Support
+
+Messages can be associated with a context (any record) and a tenant (for broader visibility):
+
+```ruby
+# Send a message with context and tenant
+user.send_message(
+  recipients: recipient,
+  body: "Hello!",
+  context: some_record,  # Optional: Any ActiveRecord model
+  tenant: organization   # Optional: Any ActiveRecord model
+)
+
+# Find topics by context
+Topic.with_context(some_record)
+
+# Find topics by tenant
+Topic.with_tenant(organization)
+
+# Find topics by both context and tenant
+Topic.with_context_and_tenant(some_record, organization)
+```
+
+This allows you to:
+
+- Organize conversations around specific records (e.g., Order, Project, Task)
+- Control visibility of conversations across different scopes (e.g., Organizations, Teams)
+- Query conversations based on their context or tenant
+
+## Requirements
+
+- Ruby >= 3.0.0
+- Rails >= 8.0.1
+- PostgreSQL (for array type support)
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+$ bundle install
+$ bundle exec rake spec
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Developed and maintained by [Ben](https://github.com/getnvoi).

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/assets/stylesheets/convo/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/convo/application_controller.rb

@@ -0,0 +1,4 @@
+module Convo
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/convo/application_helper.rb

@@ -0,0 +1,4 @@
+module Convo
+  module ApplicationHelper
+  end
+end

data/app/jobs/convo/application_job.rb

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

data/app/mailers/convo/application_mailer.rb

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

data/app/models/concerns/convo/metadata_extension.rb

@@ -0,0 +1,21 @@
+module Convo
+  module MetadataExtension
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def metadata_accessor(*fields)
+        fields.each do |field|
+          # Getter
+          define_method(field) do
+            metadata[field.to_s]
+          end
+
+          # Setter
+          define_method("#{field}=") do |value|
+            self.metadata = metadata.merge(field.to_s => value)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/convo/application_record.rb

@@ -0,0 +1,5 @@
+module Convo
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/convo/message.rb

@@ -0,0 +1,18 @@
+module Convo
+  class Message < ApplicationRecord
+    include(Convo::MetadataExtension)
+
+    belongs_to(:topic)
+    belongs_to(:sender, polymorphic: true)
+    belongs_to(:recipient, polymorphic: true)
+    belongs_to(:context, polymorphic: true, optional: true)
+    belongs_to(:tenant, polymorphic: true, optional: true)
+
+    validates(:body, presence: true)
+    validates(:sender, presence: true)
+    validates(:recipient, presence: true)
+    validates(:topic, presence: true)
+
+    has_many_attached(:files)
+  end
+end

data/app/models/convo/topic.rb

@@ -0,0 +1,82 @@
+module Convo
+  class Topic < ApplicationRecord
+    include Convo::MetadataExtension
+
+    validates :participant_ids, presence: true
+    validates :model_class, presence: true
+    validate :unique_participant_combination
+
+    has_many :messages, dependent: :destroy
+    has_many :files, through: :messages, source: :files_attachments
+
+    # Scopes for finding topics by context and tenant
+    scope :with_context, ->(context) {
+      joins(:messages).where(convo_messages: { context: }).distinct
+    }
+
+    scope :with_tenant, ->(tenant) {
+      joins(:messages).where(convo_messages: { tenant: }).distinct
+    }
+
+    scope :with_context_and_tenant, ->(context, tenant) {
+      joins(:messages)
+        .where(convo_messages: { context:, tenant: })
+        .distinct
+    }
+
+    def self.find_or_create_by_participant_ids(model_class, participant_ids, metadata: {})
+      sorted_ids = participant_ids.map(&:to_i).sort
+      transaction do
+        find_by(model_class:, participant_ids: sorted_ids) ||
+          create!(model_class:, participant_ids: sorted_ids, metadata:)
+      end
+    end
+
+    def self.send_message(sender:, recipients:, body:, context: nil, tenant: nil, metadata: {})
+      recipients = Array(recipients)
+      validate_participants_class!(sender, recipients)
+
+      participant_ids = ([ sender.id ] + recipients.map(&:id)).sort
+      topic = find_or_create_by_participant_ids(
+        sender.class.name,
+        participant_ids,
+        metadata:
+      )
+
+      transaction do
+        recipients.each do |recipient|
+          topic.messages.create!(
+            sender:,
+            recipient:,
+            body:,
+            context:,
+            tenant:,
+            metadata:
+          )
+        end
+      end
+
+      topic
+    end
+
+    private
+
+    def unique_participant_combination
+      return unless model_class.present? && participant_ids.present?
+
+      existing = self.class.where(model_class:)
+                          .where("participant_ids @> ARRAY[?]::bigint[] AND participant_ids <@ ARRAY[?]::bigint[]",
+                                participant_ids, participant_ids)
+                          .where.not(id:)
+                          .exists?
+
+      errors.add(:participant_ids, "combination already exists") if existing
+    end
+
+    def self.validate_participants_class!(sender, recipients)
+      unless recipients.all? { |r| r.class == sender.class }
+        raise ArgumentError, "Sender and recipients must be of same class"
+      end
+    end
+  end
+end

data/app/models/user.rb

@@ -0,0 +1,5 @@
+class User < ApplicationRecord
+  include Convo::HasConvo
+
+  # ... rest of the User model code
+end

data/app/views/layouts/convo/application.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Convo</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "convo/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,2 @@
+Convo::Engine.routes.draw do
+end

data/db/migrate/20250111142150_create_convo_topics.rb

@@ -0,0 +1,33 @@
+class CreateConvoTopics < ActiveRecord::Migration[7.1]
+  def up
+    create_table :convo_topics do |t|
+      t.string :model_class, null: false
+      t.bigint :participant_ids, array: true, null: false, default: []
+      t.jsonb :metadata, default: {}, null: false
+      t.timestamps
+    end
+
+    # Create the sort_array function
+    execute <<-SQL
+      CREATE OR REPLACE FUNCTION sort_array(anyarray)
+      RETURNS anyarray AS $$
+        SELECT array_agg(x ORDER BY x)
+        FROM unnest($1) x;
+      $$ LANGUAGE SQL IMMUTABLE;
+    SQL
+
+    # Create the unique index using our new function
+    execute <<-SQL
+      CREATE UNIQUE INDEX index_convo_topics_on_sorted_participant_ids
+      ON convo_topics (model_class, sort_array(participant_ids::bigint[]));
+    SQL
+
+    # Add GIN index for metadata
+    add_index :convo_topics, :metadata, using: :gin
+  end
+
+  def down
+    drop_table :convo_topics
+    execute "DROP FUNCTION IF EXISTS sort_array(anyarray);"
+  end
+end

data/db/migrate/20250111142238_create_convo_messages.rb

@@ -0,0 +1,22 @@
+class CreateConvoMessages < ActiveRecord::Migration[7.1]
+  def change
+    create_table :convo_messages do |t|
+      t.references :topic, null: false, foreign_key: { to_table: :convo_topics }
+      t.references :sender, polymorphic: true, null: false
+      t.references :recipient, polymorphic: true, null: false
+      t.references :context, polymorphic: true
+      t.references :tenant, polymorphic: true
+      t.text :body
+      t.jsonb :metadata, default: {}, null: false
+
+      t.timestamps
+    end
+
+    # Add composite indexes for polymorphic associations
+    add_index :convo_messages, [ :sender_type, :sender_id ]
+    add_index :convo_messages, [ :recipient_type, :recipient_id ]
+    add_index :convo_messages, [ :context_type, :context_id ]
+    add_index :convo_messages, [ :tenant_type, :tenant_id ]
+    add_index :convo_messages, :metadata, using: :gin
+  end
+end

data/db/migrate/20250111142300_create_active_storage_tables.rb

@@ -0,0 +1,57 @@
+# This migration comes from active_storage (originally 20170806125915)
+class CreateActiveStorageTables < ActiveRecord::Migration[7.1]
+  def change
+    # Use Active Record's configured type for primary and foreign keys
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :active_storage_blobs, id: primary_key_type do |t|
+      t.string   :key,          null: false
+      t.string   :filename,     null: false
+      t.string   :content_type
+      t.text     :metadata
+      t.string   :service_name, null: false
+      t.bigint   :byte_size,    null: false
+      t.string   :checksum
+
+      if connection.supports_datetime_with_precision?
+        t.datetime :created_at, precision: 6, null: false
+      else
+        t.datetime :created_at, null: false
+      end
+
+      t.index [ :key ], unique: true
+    end
+
+    create_table :active_storage_attachments, id: primary_key_type do |t|
+      t.string     :name,     null: false
+      t.references :record,   null: false, polymorphic: true, index: false, type: foreign_key_type
+      t.references :blob,     null: false, type: foreign_key_type
+
+      if connection.supports_datetime_with_precision?
+        t.datetime :created_at, precision: 6, null: false
+      else
+        t.datetime :created_at, null: false
+      end
+
+      t.index [ :record_type, :record_id, :name, :blob_id ], name: :index_active_storage_attachments_uniqueness, unique: true
+      t.foreign_key :active_storage_blobs, column: :blob_id
+    end
+
+    create_table :active_storage_variant_records, id: primary_key_type do |t|
+      t.belongs_to :blob, null: false, index: false, type: foreign_key_type
+      t.string :variation_digest, null: false
+
+      t.index [ :blob_id, :variation_digest ], name: :index_active_storage_variant_records_uniqueness, unique: true
+      t.foreign_key :active_storage_blobs, column: :blob_id
+    end
+  end
+
+  private
+    def primary_and_foreign_key_types
+      config = Rails.configuration.generators
+      setting = config.options[config.orm][:primary_key_type]
+      primary_key_type = setting || :primary_key
+      foreign_key_type = setting || :bigint
+      [ primary_key_type, foreign_key_type ]
+    end
+end

data/lib/convo/engine.rb

@@ -0,0 +1,25 @@
+module Convo
+  class Engine < ::Rails::Engine
+    isolate_namespace Convo
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.fixture_replacement :factory_bot
+      g.factory_bot dir: "spec/factories"
+    end
+
+    initializer "convo.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        include Convo::HasConvo
+      end
+    end
+
+    initializer "convo.migrations" do |app|
+      unless app.root.to_s.match?(root.to_s)
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path
+        end
+      end
+    end
+  end
+end

data/lib/convo/has_convo.rb

@@ -0,0 +1,34 @@
+module Convo
+  module HasConvo
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :topics,
+        -> { distinct },
+        class_name: "Convo::Topic",
+        foreign_key: :participant_ids,
+        primary_key: :id
+
+      has_many :sent_messages,
+        class_name: "Convo::Message",
+        foreign_key: :sender_id
+
+      has_many :received_messages,
+        class_name: "Convo::Message",
+        foreign_key: :recipient_id
+    end
+
+    def send_message(to:, body:)
+      Convo::Topic.send_message(
+        sender: self,
+        recipients: Array(to),
+        body: body
+      )
+    end
+
+    def conversations
+      Convo::Topic.where(model_class: self.class.name)
+                  .where("? = ANY(participant_ids)", id)
+    end
+  end
+end

data/lib/convo/version.rb

@@ -0,0 +1,3 @@
+module Convo
+  VERSION = "0.1.0"
+end

data/lib/convo.rb

@@ -0,0 +1,6 @@
+require "convo/engine"
+require "convo/has_convo"
+
+module Convo
+  # Your code goes here...
+end

data/lib/tasks/convo_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :convo do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,184 @@
+--- !ruby/object:Gem::Specification
+name: convo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ben
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-01-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.1
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.1
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: shoulda-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner-active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Convo is a Rails engine that provides a flexible and customizable conversation
+  system for your Rails application, supporting threaded comments, notifications,
+  and moderation.
+email:
+- ben@dee.mx
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/convo/application.css
+- app/controllers/convo/application_controller.rb
+- app/helpers/convo/application_helper.rb
+- app/jobs/convo/application_job.rb
+- app/mailers/convo/application_mailer.rb
+- app/models/concerns/convo/metadata_extension.rb
+- app/models/convo/application_record.rb
+- app/models/convo/message.rb
+- app/models/convo/topic.rb
+- app/models/user.rb
+- app/views/layouts/convo/application.html.erb
+- config/routes.rb
+- db/migrate/20250111142150_create_convo_topics.rb
+- db/migrate/20250111142238_create_convo_messages.rb
+- db/migrate/20250111142300_create_active_storage_tables.rb
+- lib/convo.rb
+- lib/convo/engine.rb
+- lib/convo/has_convo.rb
+- lib/convo/version.rb
+- lib/tasks/convo_tasks.rake
+homepage: https://github.com/getnvoi/convo
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/getnvoi/convo
+  source_code_uri: https://github.com/getnvoi/convo
+  changelog_uri: https://github.com/getnvoi/convo/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: A Rails engine for adding conversation and commenting functionality
+test_files: []