mixin_bot 3.0.0 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c6e5421b12eabf2c32c0500c1b828228fd24a10855047f2f7f1bf605dc62ada
-  data.tar.gz: a18da86395abe9053e52d70965538359cbbada5bc13439196c73536382d05c87
+  metadata.gz: 520bf980215da4e70c9fa6ae1d9297874fc16fc8264a43bb019a126f0fb0d555
+  data.tar.gz: 1d5cf99a0e645d4ae110e73148b501bd5f942b3f2c0e9ac0a4338d2d38699a7a
 SHA512:
-  metadata.gz: 4a20f4ef42062cff12ff5ecb280f8d447528ee2f7882e0425783af545b57a3fe7faecf36ca7c70387e5c3dbeb08cdcea02729b919cddadb386fe76b5b6d45fa6
-  data.tar.gz: f9f88a933a44502b2709fd282c8170adf73653d46721c83044358b59434444b10efac60ef82b84cb470cffaf7d4694d7bbeb270dc851c54ba5a66e40ff285713
+  metadata.gz: b73f1bd21043e018410555d93a537b2314f3398a174bf7ce443cce1652b578e425569faa9118d413789607f106863dbf08b1b79ef4da643f28c40fdbad065479
+  data.tar.gz: 49b66d6300397db22af3f28688eca9999a68ad47f07689a84f94a6c43831d96e0ad42c88d7b95cb3a12f531ab4bf4d5540f84cb0f070508687027f20337ff36a

data/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — MixinBot
 
-Ruby gem (v3.0.0): Mixin Network REST SDK + `mixinbot` CLI. Parity targets: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client), [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client).
+Ruby gem (v3.0.2): Mixin Network REST SDK + `mixinbot` CLI. Parity targets: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client), [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client).
 
 ## Commands
 

data/API_COVERAGE.md

@@ -81,6 +81,7 @@ Status values: `done` | `alias` | `n/a` (CLI-only / config / platform-specific)
 | **Snapshots** |
 | SafeSnapshots* | `API#safe_snapshots` | GET `/safe/snapshots` | done |
 | SafeSnapshotById | `API#safe_snapshot` | GET `/safe/snapshots/:id` | done |
+| SafeSnapshotByTrace | `API#safe_snapshot_by_trace` | GET `/safe/snapshots/trace/:trace_id` | done |
 | SafeNotifySnapshot | `API#create_safe_snapshot_notification` | POST notifications | done |
 | Snapshots / SnapshotById / SnapshotByTraceId | `API#snapshots`, `#snapshot`, `#snapshot_by_trace_id` | legacy | done |
 | NetworkSnapshot* | `API#network_snapshot(s)` | legacy | done |

data/CHANGELOG.md

@@ -5,7 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [3.0.2] - 2026-09-24
+
+### Added
+
+- **`MixinBot::API#update_app_security`** — `POST /apps/:id/security`, the endpoint that persists an app's `allowed_ips` and `resource_patterns`. The generic `update_app` endpoint silently ignores both fields, so code that tried to manage the resource-pattern whitelist through it was a no-op.
+
+## [3.0.1] - 2026-09-19
+
+### Fixed
+
+- **Blaze reconnect backoff no longer resets on short-lived connections.** `Reactor::STABLE_PERIOD` (the lifetime a connection needs for the backoff to reset) was exactly `MAX_BACKOFF` (30s), so any failure mode that closes sessions at a ~30s lifetime (e.g. a gateway throttling abusive reconnect patterns) read as "stable" on every cycle — the backoff pinned at the initial 1s and the reactor reconnected hot indefinitely, which is itself the abuse pattern that triggers such throttling. `STABLE_PERIOD` is now 120s (well above every single backoff step) and `MAX_BACKOFF` grows the ceiling to 300s so a sustained failure mode backs off hard while a single transient blip still reconnects in ~1s.
 
 ## [3.0.0] - 2026-09-15
 

data/README.md

@@ -6,7 +6,7 @@ Ruby SDK and CLI for [Mixin Network](https://developers.mixin.one/docs): authent
 
 The gem aims for **parity with the official [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client)** Go SDK and **[bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client)** Node SDK. See [API_COVERAGE.md](API_COVERAGE.md) for the full mapping; run `rake mixin_bot:api_coverage` to confirm no gaps are marked missing.
 
-Current gem version: **3.0.0** (see [CHANGELOG.md](CHANGELOG.md) for breaking changes and deprecations).
+Current gem version: **3.0.2** (see [CHANGELOG.md](CHANGELOG.md) for breaking changes and deprecations).
 
 ## Requirements
 
@@ -327,6 +327,80 @@ Operational notes:
 - **Phased restarts keep the old handler code** in the hosting process until a full restart; the same applies to Solid Queue's plugin.
 - Workers that need to *send* messages should use the REST API (`create_message` / `create_messages`), not the socket.
 
+## Rails integration
+
+The gem ships Rails generators under the `mixin_bot:` namespace. The first one sets up **"Sign in with Mixin"** (OAuth login via [`omniauth-mixin`](https://github.com/an-lee/omniauth-mixin)), modeled on Rails' built-in `rails g authentication`:
+
+```bash
+rails generate mixin_bot:authentication
+```
+
+This creates an identity-only Mixin login: OmniAuth initializer, `User` / `Session` / `Current` models, `SessionsController` with the OAuth callback, an `Authentication` controller concern (injected into `ApplicationController`), a sign-in view, routes, and the `CreateUsers` / `CreateSessions` migrations. It also adds `omniauth-mixin` and `omniauth-rails_csrf_protection` to the Gemfile (uncommenting existing entries, otherwise `bundle add`) and runs migrations generation. Run `bin/rails db:migrate` afterwards.
+
+Then:
+
+- Set `MIXIN_CLIENT_ID` and `MIXIN_CLIENT_SECRET` from the [Mixin Developer Dashboard](https://developers.mixin.one/dashboard).
+- Register `https://<your-host>/auth/mixin/callback` as the OAuth redirect URL of your Mixin app.
+
+Notes:
+
+- **Identity only** — the OAuth exchange is used to establish identity (Mixin user id + name + avatar). Access/refresh tokens are not persisted; a future generator may add API-access wiring on top.
+- **Fail loud at sign-in, not at boot** — the app boots fine without credentials (deploys, CI, `assets:precompile`); attempting to sign in raises an error naming the missing `MIXIN_CLIENT_ID` / `MIXIN_CLIENT_SECRET`.
+- **CSRF-protected request phase** — the sign-in button POSTs to `/auth/mixin` (OmniAuth 2.x default request method, protected by `omniauth-rails_csrf_protection`); the provider redirects back to the `/auth/mixin/callback` GET route.
+- **Existing apps beware** — like `rails g authentication`, the generator templates over target files (e.g. an existing `User` model) and will prompt on conflicts; reconcile manually if you already have users.
+- Sessions are database-backed (`sessions` table with `ip_address` / `user_agent`) with a signed httponly cookie, exactly like Rails 8's `authentication` generator; `Current.user` is available after sign-in.
+
+The generated code depends only on Rails and the two OmniAuth gems — not on `mixin_bot` itself — so the login keeps working even if you later drop the gem from the app.
+
+### The full Rails integration layer (`require 'mixin_bot/rails'`)
+
+Beyond the generators, the gem ships an optional runtime integration layer. It is opt-in and Rails stays a soft dependency:
+
+```ruby
+# config/application.rb, after Bundler.require
+require 'mixin_bot/rails'
+```
+
+Or scaffold everything in one command and skip pieces as needed:
+
+```bash
+rails generate mixin_bot:install
+rails generate mixin_bot:install --skip-notifications --skip-transfers
+```
+
+What each piece gives you:
+
+- **Blaze message routing** — `MixinBot::Blaze::Router` is a callable that plugs into `config.blaze_handler`. Handlers live in `app/mixin/handlers`, receive a decoded `Message`, and reply over the HTTP message API (no WebSocket access needed):
+
+  ```ruby
+  # config/initializers/mixin_bot_blaze.rb (generated by `rails g mixin_bot:blaze`)
+  Rails.application.config.to_prepare do
+    MixinBot.configure do
+      self.blaze_handler = MixinBot::Blaze::Router.new do
+        on 'text', Mixin::Handlers::TextHandler       # 'text' => PLAIN_TEXT
+        on 'transfer', Mixin::Handlers::TransferHandler
+      end
+    end
+  end
+  ```
+
+  Pair with the Puma plugin (`plugin :mixin_blaze`) so messages are received inside the web process tree. Per-bot: `MixinBot::Blaze::Router.new(api: MixinBot.bot(:shop))`.
+
+- **Outputs polling** — `rails g mixin_bot:outputs` creates a receipt table (unique per `bot_app_id` + `output_id` — the dedup gate) and an example processor in `app/mixin/processors`. The poller's resume cursor is derived from the receipts themselves (newest recorded output `sequence` per bot — unique, monotonic, and the key the outputs API paginates on) — no separate cursor table. Run `rails mixin_bot:poller` (standalone process; pass `[bot_name]` for a registered bot). Every output — inbound *and* outbound — is delivered to matching processors through your job queue; memos bridge lazily via the snapshot notification API. Processors implement `self.matches?(envelope)` + `#process` and should be idempotent (dispatch is at-least-once).
+
+- **Outbound transfers** — `rails g mixin_bot:transfers` creates a `MixinTransfer` ledger with the state machine (`pending → broadcast → confirmed | failed | reconciling`). Creating a record enqueues the Safe pipeline with the record's `trace_id` as the request id — retries are network-deduplicated. A timeout after submission lands in `reconciling`; the recurring `MixinTransfers.ReconcileJob` confirms from the trace snapshot or re-sends safely.
+
+- **Mixin notifications** — `rails g mixin_bot:notifications` adds `noticed` and an example notification with `deliver_by :mixin`. The channel (`MixinBot::Notifications::MixinChannel`) sends text/post/app-card messages with the configured bot's credentials; it loads only when Noticed is present.
+
+Multiple bots in one process: register named bots, then reference them everywhere (`MixinBot.bot(:shop)`, `mixin_bot:poller[shop]`, `Router.new(api: ...)`, `deliver_by :mixin, bot: :shop`):
+
+```ruby
+MixinBot.register_bot :shop,
+                      app_id: '...', session_id: '...',
+                      session_private_key: '...', server_public_key: '...',
+                      spend_key: '...'
+```
+
 ## Deep links and bot auth
 
 ```ruby

data/docs/agent/cookbook.md

@@ -156,6 +156,29 @@ Operational notes:
 - **Phased restarts keep old handler code** in the hosting process until a full restart.
 - Workers that need to *send* messages use the REST API (`create_message`), not the socket.
 
+## Mixin login for a Rails app (`rails g mixin_bot:authentication`)
+
+Task: add "Sign in with Mixin" (OAuth identity login) to an existing Rails app.
+
+```bash
+bundle add mixin_bot            # if not already present
+rails generate mixin_bot:authentication
+bin/rails db:migrate
+```
+
+Generated: `config/initializers/omniauth.rb` (OmniAuth `:mixin` provider), `app/models/{user,session,current}.rb`, `app/controllers/sessions_controller.rb` + `app/controllers/concerns/authentication.rb` (injected into `ApplicationController`), `app/views/sessions/new.html.erb`, `resource :session` + `/auth/mixin/callback` routes, and `CreateUsers` (`mixin_user_id` unique, `name`, `avatar_url`) / `CreateSessions` migrations. The Gemfile gains `omniauth-mixin` and `omniauth-rails_csrf_protection`.
+
+Required environment: `MIXIN_CLIENT_ID`, `MIXIN_CLIENT_SECRET` (from the Mixin Developer Dashboard); register `https://<host>/auth/mixin/callback` as the OAuth redirect URL.
+
+Behavior notes for agents:
+
+- **Identity only** — sign-in stores the Mixin user id + name + avatar (`User.find_or_create_by_mixin_auth!`, matched by uid). OAuth access/refresh tokens are never persisted; do not add token columns to the generated models.
+- **Boot is safe without credentials** (CI / `assets:precompile`); a sign-in attempt without them raises `ArgumentError` naming the missing env vars (OmniAuth setup phase).
+- **Request phase is POST + CSRF** (`button_to` → `/auth/mixin`, `omniauth-rails_csrf_protection`); callback is the GET route → `sessions#create`. A GET to `/auth/mixin` is rejected (OmniAuth 2.x).
+- **Sessions** are DB-backed (`sessions` rows, `ip_address`/`user_agent`) remembered in a signed httponly cookie; `Current.user` after sign-in; unauthenticated requests redirect to the sign-in page and return after login; `terminate_session` on sign-out.
+- **Self-contained** — generated code references no `mixin_bot` APIs; the login survives removing the gem. Re-running the generator does not duplicate routes or Gemfile entries; template conflicts prompt like any Rails generator (an existing `User` model is overwritten only if you choose so).
+- To call Mixin APIs on behalf of a signed-in user afterwards, use the gem's OAuth machinery (`MixinBot::API` with delegated authorization) separately from the generated authentication code.
+
 ## Discover API methods
 
 ```bash

data/lib/generators/mixin_bot/authentication/USAGE

@@ -0,0 +1,29 @@
+Description:
+    Adds "Sign in with Mixin" to this Rails application using OmniAuth
+    (omniauth-mixin): User/Session/Current models, a sessions controller with
+    the OAuth callback, an authentication concern, routes, migrations, and
+    the OmniAuth initializer.
+
+    The generated login is identity-only: the OAuth access token is used to
+    establish identity and is not persisted.
+
+    After generating, set MIXIN_CLIENT_ID and MIXIN_CLIENT_SECRET, and register
+    https://<your-host>/auth/mixin/callback as the OAuth redirect URL in the
+    Mixin developer dashboard.
+
+Example:
+    rails generate mixin_bot:authentication
+
+    This will create:
+        config/initializers/omniauth.rb
+        app/models/user.rb
+        app/models/session.rb
+        app/models/current.rb
+        app/controllers/sessions_controller.rb
+        app/controllers/concerns/authentication.rb
+        app/views/sessions/new.html.erb
+        db/migrate/xxx_create_users.rb
+        db/migrate/xxx_create_sessions.rb
+
+    It will also add `omniauth-mixin` and `omniauth-rails_csrf_protection` to
+    the Gemfile and inject `include Authentication` into ApplicationController.

data/lib/generators/mixin_bot/authentication/authentication_generator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module MixinBot
+  module Generators
+    # `rails generate mixin_bot:authentication` — sets up "Sign in with Mixin"
+    # via OmniAuth, modeled on Rails' built-in `authentication` generator.
+    # Identity only: the OAuth tokens are used to establish identity and are
+    # not persisted.
+    class AuthenticationGenerator < Rails::Generators::Base
+      # Rails 8.1 moved bundle_command out of Actions into BundleHelper.
+      unless method_defined?(:bundle_command) || private_method_defined?(:bundle_command)
+        begin
+          require 'rails/generators/bundle_helper'
+          include Rails::Generators::BundleHelper
+        rescue LoadError
+          # Older Rails ships bundle_command in Rails::Generators::Actions.
+        end
+      end
+
+      source_root File.expand_path('templates', __dir__)
+
+      SESSION_ROUTE = 'resource :session, only: [:new, :destroy]'
+      CALLBACK_ROUTE = "get '/auth/mixin/callback', to: 'sessions#create'"
+      OMNIAUTH_GEMS = %w[omniauth-mixin omniauth-rails_csrf_protection].freeze
+
+      def create_authentication_files
+        template 'config/initializers/omniauth.rb'
+        template 'app/models/user.rb'
+        template 'app/models/session.rb'
+        template 'app/models/current.rb'
+        template 'app/controllers/sessions_controller.rb'
+        template 'app/controllers/concerns/authentication.rb'
+        template 'app/views/sessions/new.html.erb'
+      end
+
+      def configure_application_controller
+        inject_into_class 'app/controllers/application_controller.rb', 'ApplicationController', "  include Authentication\n"
+      end
+
+      def configure_authentication_routes
+        route SESSION_ROUTE
+        route CALLBACK_ROUTE
+      end
+
+      def add_migrations
+        generate 'migration', 'CreateUsers', 'mixin_user_id:string!:uniq name:string avatar_url:string', '--force'
+        generate 'migration', 'CreateSessions', 'user:references ip_address:string user_agent:string', '--force'
+      end
+
+      def add_omniauth_gems
+        gemfile = File.read(gemfile_path)
+        uncommented = []
+
+        OMNIAUTH_GEMS.each do |name|
+          pattern = /gem\s+["']#{Regexp.escape(name)}["']/
+          next if gemfile.match?(/^\s*#{pattern}/) # already present
+
+          if gemfile.match?(/^\s*#\s*#{pattern}/)
+            uncomment_lines 'Gemfile', pattern
+            uncommented << name
+          else
+            # Single positional call: bundle_command signatures differ across
+            # railties versions (8.1 BundleHelper is (command, env, params);
+            # older Actions is (command, options)) — only this shape is valid
+            # on all of them, and bundler handles --quiet itself.
+            bundle_command("add #{name} --quiet")
+          end
+        end
+
+        bundle_command('install --quiet') unless uncommented.empty?
+      end
+
+      private
+
+      def gemfile_path
+        File.expand_path('Gemfile', destination_root)
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot/authentication/templates/app/controllers/concerns/authentication.rb.tt

@@ -0,0 +1,52 @@
+module Authentication
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :require_authentication
+    helper_method :authenticated?
+  end
+
+  class_methods do
+    def allow_unauthenticated_access(**options)
+      skip_before_action :require_authentication, **options
+    end
+  end
+
+  private
+    def authenticated?
+      resume_session
+    end
+
+    def require_authentication
+      resume_session || request_authentication
+    end
+
+    def resume_session
+      Current.session ||= find_session_by_cookie
+    end
+
+    def find_session_by_cookie
+      Session.find_by(id: cookies.signed[:session_id]) if cookies.signed[:session_id]
+    end
+
+    def request_authentication
+      session[:return_to_after_authenticating] = request.url
+      redirect_to new_session_path
+    end
+
+    def after_authentication_url
+      session.delete(:return_to_after_authenticating) || root_url
+    end
+
+    def start_new_session_for(user)
+      user.sessions.create!(user_agent: request.user_agent, ip_address: request.remote_ip).tap do |session|
+        Current.session = session
+        cookies.signed.permanent[:session_id] = { value: session.id, httponly: true, same_site: :lax }
+      end
+    end
+
+    def terminate_session
+      Current.session&.destroy
+      cookies.delete(:session_id)
+    end
+end

data/lib/generators/mixin_bot/authentication/templates/app/controllers/sessions_controller.rb.tt

@@ -0,0 +1,24 @@
+class SessionsController < ApplicationController
+  allow_unauthenticated_access only: %i[new create]
+
+  def new
+  end
+
+  def create
+    auth = request.env["omniauth.auth"]
+
+    unless auth
+      redirect_to new_session_path, alert: "Sign in with Mixin failed. Please try again."
+      return
+    end
+
+    user = User.find_or_create_by_mixin_auth!(auth)
+    start_new_session_for user
+    redirect_to after_authentication_url
+  end
+
+  def destroy
+    terminate_session
+    redirect_to new_session_path, status: :see_other
+  end
+end

data/lib/generators/mixin_bot/authentication/templates/app/models/current.rb.tt

@@ -0,0 +1,4 @@
+class Current < ActiveSupport::CurrentAttributes
+  attribute :session
+  delegate :user, to: :session, allow_nil: true
+end

data/lib/generators/mixin_bot/authentication/templates/app/models/session.rb.tt

@@ -0,0 +1,3 @@
+class Session < ApplicationRecord
+  belongs_to :user
+end

data/lib/generators/mixin_bot/authentication/templates/app/models/user.rb.tt

@@ -0,0 +1,12 @@
+class User < ApplicationRecord
+  has_many :sessions, dependent: :destroy
+
+  # Finds or creates the user for an OmniAuth auth hash and refreshes the
+  # stored Mixin profile (name, avatar). The OAuth exchange is used only to
+  # establish identity; credentials are not stored.
+  def self.find_or_create_by_mixin_auth!(auth)
+    user = find_or_create_by!(mixin_user_id: auth.uid)
+    user.update!(name: auth.info.name, avatar_url: auth.info.image)
+    user
+  end
+end

data/lib/generators/mixin_bot/authentication/templates/app/views/sessions/new.html.erb.tt

@@ -0,0 +1,3 @@
+<p style="color: red"><%%= alert %></p>
+
+<%%= button_to "Sign in with Mixin", "/auth/mixin", data: { turbo: false } %>

data/lib/generators/mixin_bot/authentication/templates/config/initializers/omniauth.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "omniauth"
+require "omniauth/strategies/mixin"
+
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :mixin,
+           ENV.fetch("MIXIN_CLIENT_ID", nil),
+           ENV.fetch("MIXIN_CLIENT_SECRET", nil),
+           setup: lambda { |env|
+             client_id = ENV["MIXIN_CLIENT_ID"]
+             client_secret = ENV["MIXIN_CLIENT_SECRET"]
+
+             if client_id.blank? || client_secret.blank?
+               raise ArgumentError, "Missing Mixin OAuth credentials: set MIXIN_CLIENT_ID and MIXIN_CLIENT_SECRET"
+             end
+
+             env["omniauth.strategy"].options[:client_id] = client_id
+             env["omniauth.strategy"].options[:client_secret] = client_secret
+           }
+end

data/lib/generators/mixin_bot/blaze/USAGE

@@ -0,0 +1,19 @@
+Description:
+    Adds Mixin Blaze message routing to this Rails application: a routes
+    initializer wired to MixinBot's `blaze_handler`, an example text handler
+    under app/mixin/handlers, and the `mixin_blaze` Puma plugin line in
+    config/puma.rb so messages are received inside the web process tree.
+
+    Requires MixinBot bot credentials (app_id, session_id,
+    session_private_key, server_public_key) to be configured, e.g. from
+    environment variables.
+
+Example:
+    rails generate mixin_bot:blaze
+
+    This will create:
+        config/initializers/mixin_bot_blaze.rb
+        app/mixin/handlers/text_handler.rb
+
+    It will also add `plugin :mixin_blaze` to config/puma.rb (creating it
+    when missing) without duplicating an existing line.

data/lib/generators/mixin_bot/blaze/blaze_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module MixinBot
+  module Generators
+    # `rails generate mixin_bot:blaze` — scaffolds Mixin Blaze message
+    # routing: a routes initializer wired to `config.blaze_handler`, an
+    # example text handler under `app/mixin/handlers`, and the `mixin_blaze`
+    # Puma plugin line in `config/puma.rb` so the app receives messages in
+    # its own process tree.
+    class BlazeGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      PUMA_PLUGIN_LINE = 'plugin :mixin_blaze'
+      PUMA_COMMENT = '# Receive Mixin Blaze messages in the web process tree (MixinBot).'
+
+      def create_routes_initializer
+        template 'config/initializers/mixin_bot_blaze.rb'
+      end
+
+      def create_example_handler
+        template 'app/mixin/handlers/text_handler.rb'
+      end
+
+      def configure_puma_plugin
+        if File.exist?(puma_path)
+          return if File.read(puma_path).match?(/^\s*plugin\s+:mixin_blaze\b/)
+
+          append_to_file 'config/puma.rb', "\n#{PUMA_COMMENT}\n#{PUMA_PLUGIN_LINE}\n"
+        else
+          create_file 'config/puma.rb', "#{PUMA_COMMENT}\n#{PUMA_PLUGIN_LINE}\n"
+        end
+      end
+
+      private
+
+      def puma_path
+        File.expand_path('config/puma.rb', destination_root)
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot/blaze/templates/app/mixin/handlers/text_handler.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Mixin
+  module Handlers
+    # Example Blaze handler: echoes text messages back to the sender.
+    # Handlers are instantiated per message; `message` exposes decoded data,
+    # conversation/sender ids, and the `reply` helper (HTTP message API).
+    class TextHandler < MixinBot::Blaze::Router::Base
+      def handle
+        reply("You said: #{message.data}")
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot/blaze/templates/config/initializers/mixin_bot_blaze.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Mixin Blaze message routing.
+#
+# Requires bot credentials in MixinBot.configure (app_id, session_id,
+# session_private_key, server_public_key, spend_key) — typically from
+# environment variables — and the `mixin_blaze` Puma plugin in
+# config/puma.rb to actually receive messages.
+#
+# Routes dispatch decoded envelopes in registration order (first match
+# wins); handlers live under app/mixin/handlers and are re-resolved on
+# every code reload in development.
+
+Rails.application.config.to_prepare do
+  MixinBot.configure do
+    self.blaze_handler = MixinBot::Blaze::Router.new do
+      on 'text', Mixin::Handlers::TextHandler
+      # on 'transfer', Mixin::Handlers::TransferHandler
+      # on category: 'APP_CARD', handler: Mixin::Handlers::AppCardHandler
+      # on action: 'CREATE_MESSAGE', handler: ->(message) { ... }
+    end
+  end
+end

data/lib/generators/mixin_bot/install/USAGE

@@ -0,0 +1,24 @@
+Description:
+    Sets up a Mixin Messenger/Network Rails application in one command:
+    "Sign in with Mixin" (OmniAuth), Blaze message routing with the Puma
+    plugin, the outputs poller with an example processor, the outbound
+    transfer ledger, and Noticed-driven Mixin notifications.
+
+    Skip any component:
+
+        rails generate mixin_bot:install --skip-notifications --skip-transfers
+        rails generate mixin_bot:install --skip notifications,transfers
+        rails generate mixin_bot:install --skip authentication
+
+Example:
+    rails generate mixin_bot:install
+
+    This will run, in order:
+        rails generate mixin_bot:authentication
+        rails generate mixin_bot:blaze
+        rails generate mixin_bot:outputs
+        rails generate mixin_bot:transfers
+        rails generate mixin_bot:notifications
+
+    Afterwards: set your bot credentials, run `rails db:migrate`, and start
+    the poller (`rails mixin_bot:poller`) and your job backend.

data/lib/generators/mixin_bot/install/install_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module MixinBot
+  module Generators
+    # `rails generate mixin_bot:install` — one-command setup: runs every
+    # component generator in dependency order. Skip any of them:
+    #
+    #   rails g mixin_bot:install --skip-notifications --skip-transfers
+    #   rails g mixin_bot:install --skip notifications transfers
+    #   rails g mixin_bot:install --skip=notifications,transfers
+    #
+    # Idempotent: each component generator (and this one) is safe to re-run.
+    class InstallGenerator < Rails::Generators::Base
+      COMPONENTS = %w[authentication blaze outputs transfers notifications].freeze
+
+      class_option :skip,
+                   type: :array, default: [],
+                   banner: 'component,component2',
+                   desc: "Skip components (comma-separated; any of: #{COMPONENTS.join(' ')})"
+
+      COMPONENTS.each do |component|
+        class_option :"skip_#{component}", type: :boolean, default: false,
+                                           desc: "Skip the #{component} component"
+
+        define_method(:"install_#{component}") do
+          invoke "mixin_bot:#{component}" unless skip?(component)
+        end
+      end
+
+      def show_plan
+        skipped = COMPONENTS.select { |component| skip?(component) }
+        say_status :install, if skipped.empty?
+                               'all components'
+                             else
+                               "all components except #{skipped.join(', ')}"
+                             end
+      end
+
+      private
+
+      def skip?(component)
+        return true if options[:"skip_#{component}"]
+
+        Array(options[:skip]).flat_map { |value| value.to_s.split(',') }.include?(component.to_s)
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot/notifications/USAGE

@@ -0,0 +1,13 @@
+Description:
+    Adds Noticed-driven Mixin message notifications: ensures the `noticed`
+    gem is in the Gemfile and scaffolds one example notification delivered
+    through MixinBot's Mixin channel (`deliver_by :mixin`) over the HTTP
+    message API.
+
+Example:
+    rails generate mixin_bot:notifications
+
+    This will create:
+        app/notifications/payment_received_notification.rb
+
+    It will also ensure `noticed` is present in the Gemfile.