missive 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08e4bc0cf32260c7519cd0ec0ab1b6f378b6e15f658ca559d593f5e2f69a51eb'
-  data.tar.gz: bb9b7dd6e243f03b4efb6cda902d542b0b7eec9e2e24c1e725f3237a1c39cfdb
+  metadata.gz: '06220491a9066084b07838222a15676c94543dcec8d6d7a9e3c84137e8efab14'
+  data.tar.gz: cd08afa7a073de913d16f3ffe6251c31c196696420a2f5ccd51d8c1d6bff48f0
 SHA512:
-  metadata.gz: 61713bf0d79f835d91a739073efeae708dde7033d2f64aab5f11b696b69483f532c4e795eae4db8d13c256f25b05afdf413d8262fa9a9e2c5062902d41efc82a
-  data.tar.gz: 9441fbb01803f621f33252a5e1be5fa9ff94fd5c20b5355bfe3a1e0ba44824512404fef1c28378f8ac549ba3f162910a52dbc3e1af478caf9d858b8be3f34257
+  metadata.gz: d32d340f9c5c473f320f3590339455b83408fc5854022bb4ad5888f59ee002a08cca4f8ec95bfec9b022d4557af3bad45554f44db137778c5337683c842cfbd2
+  data.tar.gz: d15612829c698aa1f4bfa5f2177033da4745a9f4d2b835972d24dea1023a186c7bfe6227b9b2fe61cdecc78cee62b955977089d7f57d775a0ab326063b992072

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.0.3] - 2026-02-04
+
+- Add associations collision checks and configuration
+
+## [0.0.2] - 2025-12-14
+
+- Add install generator
+- Add Postmark Bulk API implementation
+
 ## [0.0.1] - 2025-10-14
 
 - First release: base models, database structure

data/README.md

@@ -55,6 +55,12 @@ A lightweight Rails toolkit for building newsletter features. Missive provides t
 bundle add missive
 ```
 
+Install the migrations:
+
+```bash
+rails generate missive:install
+```
+
 ### Configuration
 
 Missive uses the same configuration as `postmark-rails`. Please follow the [`postmark-rails` configuration instructions](https://github.com/ActiveCampaign/postmark-rails?tab=readme-ov-file#installation) to set up your Postmark API credentials.
@@ -107,6 +113,54 @@ class User < ApplicationRecord
 end
 ```
 
+#### Customizing association names
+
+If your User model already has associations named `sender` or `subscriber`, you can customize the association names:
+
+```rb
+class User < ApplicationRecord
+  include Missive::User
+  configure_missive_sender(
+    sender: :missive_sender,
+    sent_dispatches: :missive_sent_dispatches,
+    sent_lists: :missive_sent_lists,
+    sent_messages: :missive_sent_messages
+  )
+  configure_missive_subscriber(
+    subscriber: :missive_subscriber,
+    dispatches: :missive_dispatches,
+    subscriptions: :missive_subscriptions,
+    subscribed_lists: :missive_subscribed_lists,
+    unsubscribed_lists: :missive_unsubscribed_lists
+  )
+end
+```
+
+Or, if including the concerns separately:
+
+```rb
+class User < ApplicationRecord
+  include Missive::UserAsSender
+  configure_missive_sender(
+    sender: :missive_sender,
+    sent_dispatches: :missive_sent_dispatches,
+    sent_lists: :missive_sent_lists,
+    sent_messages: :missive_sent_messages
+  )
+
+  include Missive::UserAsSubscriber
+  configure_missive_subscriber(
+    subscriber: :missive_subscriber,
+    dispatches: :missive_dispatches,
+    subscriptions: :missive_subscriptions,
+    subscribed_lists: :missive_subscribed_lists,
+    unsubscribed_lists: :missive_unsubscribed_lists
+  )
+end
+```
+
+You only need to customize the associations that conflict - any unconfigured associations will use their default names.
+
 #### Manage subscriptions
 
 ```rb
@@ -180,6 +234,68 @@ list.create_message!(subject: "Hello world!")
 message.send!
 ```
 
+### Sending with Postmark Bulk API
+
+Missive leverages the [Bulk Email API](https://postmarkapp.com/developer/api/bulk-email) endpoints.
+
+> [!WARNING]
+> This endpoint is available to early access customers only. You need to request access. [Learn more](https://postmarkapp.com/support/article/1311-the-early-access-program-for-the-new-bulk-api)
+
+The official [postmark gem](https://github.com/ActiveCampaign/postmark-gem) does not support these endpoints yet, so Missive ships with `Stamp`, a thin layer over Postmark's official library.
+
+#### Sending a message in bulk
+
+You can pass a Hash that matches the body expected by the API.
+
+```rb
+Missive::Stamp::ApiClient.deliver_in_bulk(
+  from: "sender@example.com",
+  subject: "Hello {{name}}",
+  html_body: "<p>Hello {{name}}</p>",
+  text_body: "Hello {{name}}",
+  messages: [
+    {
+      to: "jane.doe@example.com",
+      template_model: {name: "Jane"}
+    },
+    {
+      to: "john.doe@example.com",
+      template_model: {name: "John"}
+    }
+  ]
+)
+```
+
+You can also pass a `Mail` instance and an Array of recipients.
+
+```rb
+mail = Mail.new do
+  from "sender@example.com"
+  subject "Hello {{name}}"
+  body: "Hello {{name}}"
+end
+
+Missive::Stamp::ApiClient.deliver_message_in_bulk(
+  mail,
+  [
+    {
+      to: "jane.doe@example.com",
+      template_model: {name: "Jane"}
+    },
+    {
+      to: "john.doe@example.com",
+      template_model: {name: "John"}
+    }
+  ]
+)
+```
+
+#### Getting the status of a bulk API request
+
+```rb
+Missive::Stamp::ApiClient.get_bulk_status("f24af63c-533d-4b7a-ad65-4a7b3202d3a7")
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/models/concerns/missive/user_as_sender.rb

@@ -2,17 +2,50 @@ module Missive
   module UserAsSender
     extend ActiveSupport::Concern
 
+    class AssociationAlreadyDefinedError < StandardError; end
+
+    ASSOCIATION_NAMES = %i[sender sent_dispatches sent_lists sent_messages].freeze
+
+    class_methods do
+      def missive_sender_config
+        @missive_sender_config ||= ASSOCIATION_NAMES.index_with { |name| name }
+      end
+
+      def configure_missive_sender(options = {})
+        missive_sender_config.merge!(options)
+        _define_missive_sender_associations
+      end
+
+      def _define_missive_sender_associations
+        config = missive_sender_config
+
+        _check_missive_association_collision!(config[:sender])
+
+        has_one config[:sender], class_name: "Missive::Sender", foreign_key: :user_id, dependent: :nullify
+        has_many config[:sent_dispatches], class_name: "Missive::Dispatch", through: config[:sender], source: :dispatches
+        has_many config[:sent_lists], class_name: "Missive::List", through: config[:sender], source: :lists
+        has_many config[:sent_messages], class_name: "Missive::Message", through: config[:sender], source: :messages
+      end
+
+      def _check_missive_association_collision!(name)
+        return unless reflect_on_association(name)
+
+        raise AssociationAlreadyDefinedError,
+          "Association :#{name} is already defined on #{self.name}. " \
+          "Use configure_missive_sender to specify a different name. " \
+          "Example: configure_missive_sender(sender: :missive_sender)"
+      end
+    end
+
     included do
-      has_one :sender, class_name: "Missive::Sender", dependent: :nullify
-      has_many :sent_dispatches, class_name: "Missive::Dispatch", through: :sender, source: :dispatches
-      has_many :sent_lists, class_name: "Missive::List", through: :sender, source: :lists
-      has_many :sent_messages, class_name: "Missive::Message", through: :sender, source: :messages
+      _define_missive_sender_associations
 
       def init_sender(attributes = {})
-        self.sender = Missive::Sender.find_or_initialize_by(email:)
-        sender.assign_attributes(attributes)
-        sender.save!
-        sender
+        assoc = self.class.missive_sender_config[:sender]
+        send("#{assoc}=", Missive::Sender.find_or_initialize_by(email:))
+        send(assoc).assign_attributes(attributes)
+        send(assoc).save!
+        send(assoc)
       end
     end
   end

data/app/models/concerns/missive/user_as_subscriber.rb

@@ -2,21 +2,54 @@ module Missive
   module UserAsSubscriber
     extend ActiveSupport::Concern
 
+    class AssociationAlreadyDefinedError < StandardError; end
+
+    ASSOCIATION_NAMES = %i[subscriber dispatches subscriptions subscribed_lists unsubscribed_lists].freeze
+
+    class_methods do
+      def missive_subscriber_config
+        @missive_subscriber_config ||= ASSOCIATION_NAMES.index_with { |name| name }
+      end
+
+      def configure_missive_subscriber(options = {})
+        missive_subscriber_config.merge!(options)
+        _define_missive_subscriber_associations
+      end
+
+      def _define_missive_subscriber_associations
+        config = missive_subscriber_config
+
+        _check_missive_association_collision!(config[:subscriber])
+
+        has_one config[:subscriber], class_name: "Missive::Subscriber", foreign_key: :user_id, dependent: :destroy
+        has_many config[:dispatches], class_name: "Missive::Dispatch", through: config[:subscriber]
+        has_many config[:subscriptions], class_name: "Missive::Subscription", through: config[:subscriber]
+        has_many config[:subscribed_lists], class_name: "Missive::List", through: config[:subscriber], source: :lists
+        has_many config[:unsubscribed_lists], -> { where.not(missive_subscriptions: {suppressed_at: nil}) },
+          class_name: "Missive::List",
+          through: config[:subscriber],
+          source: :lists
+      end
+
+      def _check_missive_association_collision!(name)
+        return unless reflect_on_association(name)
+
+        raise AssociationAlreadyDefinedError,
+          "Association :#{name} is already defined on #{self.name}. " \
+          "Use configure_missive_subscriber to specify a different name. " \
+          "Example: configure_missive_subscriber(subscriber: :missive_subscriber)"
+      end
+    end
+
     included do
-      has_one :subscriber, class_name: "Missive::Subscriber", dependent: :destroy
-      has_many :dispatches, class_name: "Missive::Dispatch", through: :subscriber
-      has_many :subscriptions, class_name: "Missive::Subscription", through: :subscriber
-      has_many :subscribed_lists, class_name: "Missive::List", through: :subscriber, source: :lists
-      has_many :unsubscribed_lists, -> { where.not(missive_subscriptions: {suppressed_at: nil}) },
-        class_name: "Missive::List",
-        through: :subscriber,
-        source: :lists
+      _define_missive_subscriber_associations
 
       def init_subscriber(attributes = {})
-        self.subscriber = Missive::Subscriber.find_or_initialize_by(email:)
-        subscriber.assign_attributes(attributes)
-        subscriber.save!
-        subscriber
+        assoc = self.class.missive_subscriber_config[:subscriber]
+        send("#{assoc}=", Missive::Subscriber.find_or_initialize_by(email:))
+        send(assoc).assign_attributes(attributes)
+        send(assoc).save!
+        send(assoc)
       end
     end
   end

data/lib/generators/missive/install_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+require "rails/generators/active_record"
+
+module Missive
+  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 copy_missive_migrations
+        migration_template "migrations/install_missive.rb.erb", "db/migrate/install_missive.rb"
+      end
+
+      private
+
+      def migration_class_name
+        if Rails::VERSION::MAJOR >= 5
+          "ActiveRecord::Migration[#{ActiveRecord::Migration.current_version}]"
+        else
+          "ActiveRecord::Migration"
+        end
+      end
+    end
+  end
+end

data/lib/generators/missive/templates/migrations/install_missive.rb.erb

@@ -0,0 +1,74 @@
+class InstallMissive < <%= migration_class_name %>
+  def change
+    create_table :missive_subscribers do |t|
+      t.string :email, null: false
+      t.timestamp :suppressed_at
+      t.integer :suppression_reason
+      t.references :user, foreign_key: true
+
+      t.timestamps
+    end
+
+    create_table :missive_lists do |t|
+      t.string :name, null: false
+      t.integer :subscriptions_count, default: 0
+      t.integer :messages_count, default: 0
+      t.timestamp :last_message_sent_at
+      t.string :postmark_message_stream_id
+
+      t.timestamps
+    end
+
+    create_table :missive_messages do |t|
+      t.string :subject, null: false
+      t.integer :dispatches_count, default: 0
+      t.references :list, null: false, foreign_key: {to_table: "missive_lists"}
+      t.string :postmark_message_stream_id
+      t.timestamp :sent_at
+
+      t.timestamps
+    end
+
+    create_table :missive_dispatches do |t|
+      t.references :subscriber, null: false, foreign_key: {to_table: "missive_subscribers"}
+      t.references :message, null: false, foreign_key: {to_table: "missive_messages"}
+      t.string :postmark_message_stream_id
+      t.string :postmark_message_id
+      t.timestamp :sent_at
+      t.timestamp :delivered_at
+      t.timestamp :opened_at
+      t.timestamp :clicked_at
+      t.timestamp :suppressed_at
+      t.integer :suppression_reason
+
+      t.index [:subscriber_id, :message_id], unique: true
+
+      t.timestamps
+    end
+
+    create_table :missive_subscriptions do |t|
+      t.references :subscriber, null: false, foreign_key: {to_table: "missive_subscribers"}
+      t.references :list, null: false, foreign_key: {to_table: "missive_lists"}
+      t.timestamp :suppressed_at
+      t.integer :suppression_reason
+
+      t.index [:subscriber_id, :list_id], unique: true
+
+      t.timestamps
+    end
+
+    create_table :missive_senders do |t|
+      t.string :email, null: false
+      t.string :name
+      t.string :reply_to_email
+      t.integer :postmark_sender_signature_id
+      t.references :user, foreign_key: false
+
+      t.timestamps
+    end
+
+    add_reference :missive_dispatches, :sender, null: false, foreign_key: {to_table: "missive_senders"}
+    add_reference :missive_lists, :sender, null: false, foreign_key: {to_table: "missive_senders"}
+    add_reference :missive_messages, :sender, null: false, foreign_key: {to_table: "missive_senders"}
+  end
+end

data/lib/missive/stamp/api_client.rb

@@ -0,0 +1,40 @@
+module Missive
+  # Stamp is a thin layer over Postmark's official library,
+  # that improves it for Missive's needs.
+  #
+  # Main features:
+  # - implementation of the [Bulk API](https://postmarkapp.com/developer/api/bulk-email)
+  module Stamp
+    class ApiClient < ::Postmark::ApiClient
+      # Send bulk emails, passing a hash
+      # https://postmarkapp.com/developer/api/bulk-email#send-bulk-emails
+      def deliver_in_bulk(message_hash)
+        data = serialize(::Postmark::MessageHelper.to_postmark(message_hash))
+
+        with_retries do
+          format_response http_client.post("email/bulk", data)
+        end
+      end
+
+      # Send bulk emails, passing a message and its recipients
+      # https://postmarkapp.com/developer/api/bulk-email#send-bulk-emails
+      def deliver_message_in_bulk(message, recipients = [])
+        data = serialize(message.to_postmark_hash.merge(messages: recipients))
+
+        with_retries do
+          response, error = take_response_of { http_client.post("email/bulk", data) }
+          update_message(message, response)
+          raise error if error
+
+          format_response(response, compatible: true)
+        end
+      end
+
+      # Get the status/details of a bulk API request
+      # https://postmarkapp.com/developer/api/bulk-email#get-a-bulk-send-status
+      def get_bulk_status(id)
+        format_response http_client.get("email/bulk/#{id}")
+      end
+    end
+  end
+end

data/lib/missive/version.rb

@@ -1,3 +1,3 @@
 module Missive
-  VERSION = "0.0.1".freeze
+  VERSION = "0.0.3".freeze
 end

data/lib/missive.rb

@@ -1,5 +1,7 @@
 require "missive/version"
 require "missive/engine"
+require "postmark"
+require "missive/stamp/api_client"
 
 module Missive
   # Your code goes here...

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: missive
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Hans Lemuet
@@ -100,16 +100,13 @@ files:
 - app/models/missive/subscription.rb
 - app/views/layouts/missive/application.html.erb
 - config/routes.rb
-- db/migrate/20251002000005_create_missive_subscribers.rb
-- db/migrate/20251004191513_create_missive_lists.rb
-- db/migrate/20251004193630_create_missive_messages.rb
-- db/migrate/20251004201105_create_missive_dispatches.rb
-- db/migrate/20251006214059_create_missive_subscriptions.rb
-- db/migrate/20251013205354_create_missive_senders.rb
 - lefthook.yml
+- lib/generators/missive/install_generator.rb
+- lib/generators/missive/templates/migrations/install_missive.rb.erb
 - lib/missive.rb
 - lib/missive/engine.rb
 - lib/missive/railtie.rb
+- lib/missive/stamp/api_client.rb
 - lib/missive/version.rb
 - lib/tasks/missive_tasks.rake
 homepage: https://github.com/Spone/missive
@@ -133,7 +130,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.4
 specification_version: 4
 summary: Toolbox for managing newsletters in Rails, sending them with Postmark.
 test_files: []

data/db/migrate/20251002000005_create_missive_subscribers.rb

@@ -1,12 +0,0 @@
-class CreateMissiveSubscribers < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_subscribers do |t|
-      t.string :email, null: false
-      t.timestamp :suppressed_at
-      t.integer :suppression_reason
-      t.references :user, foreign_key: true
-
-      t.timestamps
-    end
-  end
-end

data/db/migrate/20251004191513_create_missive_lists.rb

@@ -1,13 +0,0 @@
-class CreateMissiveLists < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_lists do |t|
-      t.string :name, null: false
-      t.integer :subscriptions_count, default: 0
-      t.integer :messages_count, default: 0
-      t.timestamp :last_message_sent_at
-      t.string :postmark_message_stream_id
-
-      t.timestamps
-    end
-  end
-end

data/db/migrate/20251004193630_create_missive_messages.rb

@@ -1,13 +0,0 @@
-class CreateMissiveMessages < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_messages do |t|
-      t.string :subject, null: false
-      t.integer :dispatches_count, default: 0
-      t.references :list, null: false, foreign_key: {to_table: "missive_lists"}
-      t.string :postmark_message_stream_id
-      t.timestamp :sent_at
-
-      t.timestamps
-    end
-  end
-end

data/db/migrate/20251004201105_create_missive_dispatches.rb

@@ -1,20 +0,0 @@
-class CreateMissiveDispatches < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_dispatches do |t|
-      t.references :subscriber, null: false, foreign_key: {to_table: "missive_subscribers"}
-      t.references :message, null: false, foreign_key: {to_table: "missive_messages"}
-      t.string :postmark_message_stream_id
-      t.string :postmark_message_id
-      t.timestamp :sent_at
-      t.timestamp :delivered_at
-      t.timestamp :opened_at
-      t.timestamp :clicked_at
-      t.timestamp :suppressed_at
-      t.integer :suppression_reason
-
-      t.index [:subscriber_id, :message_id], unique: true
-
-      t.timestamps
-    end
-  end
-end

data/db/migrate/20251006214059_create_missive_subscriptions.rb

@@ -1,14 +0,0 @@
-class CreateMissiveSubscriptions < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_subscriptions do |t|
-      t.references :subscriber, null: false, foreign_key: {to_table: "missive_subscribers"}
-      t.references :list, null: false, foreign_key: {to_table: "missive_lists"}
-      t.timestamp :suppressed_at
-      t.integer :suppression_reason
-
-      t.index [:subscriber_id, :list_id], unique: true
-
-      t.timestamps
-    end
-  end
-end

data/db/migrate/20251013205354_create_missive_senders.rb

@@ -1,17 +0,0 @@
-class CreateMissiveSenders < ActiveRecord::Migration[8.0]
-  def change
-    create_table :missive_senders do |t|
-      t.string :email, null: false
-      t.string :name
-      t.string :reply_to_email
-      t.integer :postmark_sender_signature_id
-      t.references :user, foreign_key: false
-
-      t.timestamps
-    end
-
-    add_reference :missive_dispatches, :sender, null: false, foreign_key: {to_table: "missive_senders"}
-    add_reference :missive_lists, :sender, null: false, foreign_key: {to_table: "missive_senders"}
-    add_reference :missive_messages, :sender, null: false, foreign_key: {to_table: "missive_senders"}
-  end
-end