inquirex 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ce3e2bcf0a91cdba8c83abd9af02807b25462ff878762f0a0114372554dfe84
-  data.tar.gz: 017b1f51f0641f57aecd2a9c84fb3c4fb5e39b6252ac1a4de4f9735bd79d7837
+  metadata.gz: 3422d46566a55c973dc712fb60918cde34029d3dc739e36bb1eb2c40110f1f25
+  data.tar.gz: eb6e54e12a407b21547ac97ca7153b93af516713c0dbcaa83a2323f909f8f816
 SHA512:
-  metadata.gz: a426a31f57e7c3ef4e7bdeb2cd288da6fb66717436c167e0f3a03e808706f9525ea3c687055da32b3413015a80882524f88b05c6d01ea06dc5875dfb96f93521
-  data.tar.gz: 9be96813505bf0ce8a0d5eed1a3e775dd0a08b8b54a5484993abe9119663323dd8075aba8fb74d3aebeed63c82370ee04fff6488a2b72d13bfcda0a47d38b525
+  metadata.gz: 42b3c45e598ebadec67d48e251605e74022cfe1ba0923c21b5998b0c0c2ef8005f2895e43c501dfd9a8613d05821a95653330c5395ff7755fa1892a74761873c
+  data.tar.gz: c85a9f013fb304ddfc7cbb9742a24167c7da7cefe18fa83425cfc83f1ac5184eeb7960a9ee3592d95ebd82890f7b9568aaea2b1eb488d8840a17106cbe091f3f

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-19
+
+- Post-completion `action` DSL verb with an extensible effect registry
+- `send_email` effect: builds `Mail::Message` objects (multipart text/HTML) from `{{field}}` templates into `Answers#outbox`; delivery is the host application's responsibility. The `mail` gem is a soft dependency.
+- `run { |answers, outbox| ... }` escape-hatch effect (stripped from JSON)
+- `webhook` effect: POSTs the answers envelope to a static https URL whose host must be covered by the new top-level `allowed_domains` declaration; enforcement runs in `Definition#validate!`, so tampered JSON definitions fail at rehydration
+- `Inquirex::Actions::Runner` and `Inquirex::Actions.run(definition, answers)`
+- Actions serialize to/from JSON with their rule gates
+- `CompletionMetadata` (OpenStruct; `engine` and `engine_version` required) stamped by the engine at flow completion, enrichable by front-ends via the new `Engine#after_completion` hook, persisted in engine state, and merged into answers by `Engine#answers_with_metadata`
+
 ## [0.1.0] - 2026-04-13
 
 - Initial release

data/README.md

@@ -31,7 +31,7 @@ It provides a rich DSL for creating dynamic user intake forms, with complexity r
 >
 > For technically inclined, Inquirex turns user forms into a directed graph, where nodes are either questions or statements (or UI transitions), while edges are AST-based logical conditions that can be stacked and joined in arbitrarily complex ways, allowing you to move from one question to any other based on the previous answer. See the details below.
 
-***Don't want to deal with figuring it out? Head to [Qualified.At](https://qualified.at/onboarding) and walk through the demo onboarding form, that exists specifically to show you how quickly you can have the same conceptually on your site, tailored to YOUR users.***
+***Don't want to deal with figuring it out? Head to [Qualified.At](https://qualified.at) and walk through the demo onboarding form, that exists specifically to show you how quickly you can have the same conceptually on your site, tailored to YOUR users.***
 
 ## Summary
 
@@ -435,11 +435,7 @@ Behavior:
 - Use `finished?` to detect completion
 - Use `total(:price)` / `totals` to read running totals
 - Use `to_state` / `.from_state` for persistence/resume (totals included)
-- Use `prefill!(hash)` to merge externally-supplied answers into the state,
-  e.g. fields extracted by an LLM from a free-text answer (see
-  [inquirex-llm](#extension-gems)). Existing answers are preserved; `nil`
-  and empty values are ignored so they don't spuriously satisfy
-  `not_empty` rules. The engine auto-advances past any newly-skippable step.
+- Use `prefill!(hash)` to merge externally-supplied answers into the state, e.g. fields extracted by an LLM from a free-text answer (see [inquirex-llm](#extension-gems)). Existing answers are preserved; `nil` and empty values are ignored so they don't spuriously satisfy `not_empty` rules. The engine auto-advances past any newly-skippable step.
 
 ```ruby
 engine = Inquirex::Engine.new(definition)
@@ -466,6 +462,90 @@ Pass a custom adapter to the engine:
 engine = Inquirex::Engine.new(definition, validator: my_validator)
 ```
 
+## Completion Metadata
+
+When a flow finishes, the engine guarantees a `CompletionMetadata` — an OpenStruct describing how the answers were collected. Only `engine` and `engine_version` are required members; rendering front-ends attach richer environment details from an `after_completion` hook:
+
+```ruby
+engine.after_completion do |eng|
+  eng.completion_metadata = Inquirex::CompletionMetadata.new(
+    engine:         "inquirex-tty",
+    engine_version: Inquirex::TTY::VERSION,
+    uname:          OpenStruct.new(Etc.uname),
+    user:           Etc.getlogin,
+    terminal:       ENV["LC_TERMINAL"] || ENV["TERM_PROGRAM"] || "Unknown"
+  )
+end
+```
+
+If no hook supplies one, the engine stamps the minimal core version (`engine: "inquirex"`, `engine_version: Inquirex::VERSION`). The metadata persists through `Engine#to_state` / `Engine.from_state`, and `engine.answers_with_metadata` merges it into the answers hash under `:completion_metadata` — which also makes it available to post-completion actions: webhook payloads carry it, and email templates can interpolate `{{completion_metadata.engine}}`.
+
+## Post-Completion Actions
+
+After all questions are answered, `action` declarations run server-side with the collected answers. The flagship effect is `send_email`, which **builds** `Mail::Message` objects (the same object ActionMailer wraps) and attaches them to `answers.outbox` — **nothing is delivered**; the host application decides how and when to send.
+
+```ruby
+Inquirex.define id: "tax-intake-2025" do
+  allowed_domains "*.agentica.group"   # egress allowlist for webhook effects
+
+  # ... ask steps ...
+
+  action :client_receipt, if: not_empty(:email) do
+    send_email to:      "{{email}}",
+               from:    "forms@agentica.group",
+               subject: "Thanks {{name}} — we received your intake",
+               text:    <<~TEXT,
+                 Hi {{name}},
+                 We received your answers:
+
+                 {{answers_summary}}
+               TEXT
+               html:    <<~HTML
+                 <p>Hi {{name}},</p>
+                 <img src="https://cdn.agentica.group/logo.png" alt="Logo">
+                 {{answers_summary}}
+               HTML
+  end
+
+  action :admin_alert do
+    send_email to: "owner@agentica.group", from: "forms@agentica.group",
+               subject: "New lead: {{name}} <{{email}}>",
+               html: "{{answers_summary}}"
+    run { |answers, outbox| Metrics.count(:lead, answers.to_flat_h) }
+  end
+
+  action :crm_push do
+    webhook url: "https://hooks.agentica.group/inquirex",
+            headers: { "X-Api-Key" => "..." }
+  end
+end
+```
+
+Execution and delivery:
+
+```ruby
+answers = Inquirex::Actions.run(definition, engine.answers)
+answers.outbox.messages   # => [Mail::Message, ...]
+answers.outbox.results    # => per-action :ok / :skipped / :failed trail
+
+# In a Rails host:
+answers.outbox.each do |message|
+  ActionMailer::Base.wrap_delivery_behavior(message)  # adopt Rails delivery config
+  message.deliver
+end
+```
+
+Key semantics:
+
+- **Templating is `{{field}}` interpolation only** — dot-notation keys resolved against `Answers#to_flat_h`, deliberately inert (no code execution), so definitions stored in a database render safely. Values interpolated into `html:` bodies are HTML-escaped automatically; `text:` bodies stay verbatim. The built-in `{{answers_summary}}` expands to all collected answers.
+- **`if:` gates** reuse the serializable rule AST (`not_empty(:email)`, ...). A false rule records `:skipped` — declare no actions (or gate them) when a flow should only save answers.
+- **`run { |answers, outbox| ... }`** is the full-Ruby escape hatch; like all lambdas it is stripped from JSON.
+- **Failures are isolated**: a raising effect records `:failed` in `outbox.results` and never blocks other actions.
+- **Images** in HTML bodies must be external URLs; attachments are unsupported.
+- The `mail` gem is a soft dependency, needed only when a message is built (Rails hosts already have it via ActionMailer).
+- **`webhook url:`** POSTs `{"answers": {...}}` as JSON to a static URL. The URL's host must be covered by `allowed_domains`, declared at the top of the definition so the flow's egress surface is auditable at a glance. The check runs inside `Definition.new` — a JSON definition whose webhook URL was tampered with fails at *rehydration*, before anything executes. Also enforced: https only (plain http just for localhost), no userinfo, no `{{field}}` templates in URLs (the destination must be static), redirects are not followed, and non-2xx responses record `:failed`.
+- Effects are extensible: `Inquirex::Actions.register(:save_record, MyEffect)` gives a new verb both DSL and JSON wire support.
+
 ## Serialization
 
 Definitions support round-trip serialization:
@@ -483,6 +563,8 @@ Serialized structure includes:
 - Steps and transitions
 - Rule AST payloads
 - Widget hints
+- Post-completion actions (`actions`) with their rules and effects; `run` blocks are stripped, and an action left with no serializable effects is omitted entirely
+- The `allowed_domains` egress allowlist, re-enforced against webhook URLs every time a definition is rehydrated
 
 Important serialization details:
 

data/lib/inquirex/accumulator.rb

@@ -8,9 +8,21 @@ module Inquirex
   # @attr_reader name [Symbol] accumulator identifier (e.g. :price)
   # @attr_reader type [Symbol] one of Node::TYPES (typically :currency, :integer, :decimal)
   # @attr_reader default [Numeric] starting value (default: 0)
+  #
+  # @example Declare a running price total and contribute to it from a step
+  #   Inquirex.define do
+  #     accumulator :price, type: :currency, default: 0
+  #     ask :dependents do
+  #       type :integer
+  #       accumulate :price, per_unit: 50
+  #     end
+  #   end
   class Accumulator
     attr_reader :name, :type, :default
 
+    # @param name [Symbol, String] accumulator identifier
+    # @param type [Symbol, String] value type, one of Node::TYPES
+    # @param default [Numeric] starting value before any contributions
     def initialize(name:, type: :decimal, default: 0)
       @name = name.to_sym
       @type = type.to_sym
@@ -18,10 +30,19 @@ module Inquirex
       freeze
     end
 
+    # Serializes the accumulator to its wire format. The name is omitted —
+    # Definition#to_h keys the accumulators map by name.
+    #
+    # @return [Hash{String => Object}] e.g. { "type" => "currency", "default" => 0 }
     def to_h
       { "type" => @type.to_s, "default" => @default }
     end
 
+    # Deserializes an Accumulator from its wire format.
+    #
+    # @param name [Symbol, String] accumulator identifier (the map key)
+    # @param hash [Hash] type/default attributes (string or symbol keys)
+    # @return [Accumulator]
     def self.from_h(name, hash)
       new(
         name:    name,
@@ -44,10 +65,15 @@ module Inquirex
   # @attr_reader shape [Symbol] one of :lookup, :per_selection, :per_unit, :flat
   # @attr_reader payload [Object] shape-specific data (Hash or Numeric)
   class Accumulation
+    # Valid accumulation shapes; exactly one must be declared per entry.
     SHAPES = %i[lookup per_selection per_unit flat].freeze
 
     attr_reader :target, :shape, :payload
 
+    # @param target [Symbol, String] accumulator name to contribute to
+    # @param shape [Symbol, String] one of SHAPES
+    # @param payload [Hash, Numeric] shape-specific data (Hash for :lookup/:per_selection)
+    # @raise [Errors::DefinitionError] when shape is not one of SHAPES
     def initialize(target:, shape:, payload:)
       @target = target.to_sym
       @shape = shape.to_sym
@@ -73,6 +99,9 @@ module Inquirex
       end
     end
 
+    # Serializes to the single-key shape Hash that .from_h accepts.
+    #
+    # @return [Hash{String => Object}] e.g. { "per_unit" => 50 }
     def to_h
       { @shape.to_s => serialize_payload }
     end

data/lib/inquirex/actions/action.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Actions
+    # A named post-completion unit: an optional rule gating execution and an
+    # ordered list of effects. Declared with the DSL word `action`:
+    #
+    #   action :client_receipt, if: not_empty(:email) do
+    #     send_email to: "{{email}}", subject: "Thanks {{name}}!", text: "..."
+    #   end
+    #
+    # Rules reuse the same serializable AST as transitions, so conditions
+    # survive the JSON round-trip. Non-serializable effects (run blocks) are
+    # stripped on serialization; an action left with no serializable effects
+    # is omitted from JSON entirely.
+    class Action
+      attr_reader :id, :rule, :effects
+
+      # @param id [Symbol] action identifier
+      # @param effects [Array<Actions::Base>] executed in declaration order
+      # @param rule [Rules::Base, nil] gate — action runs only when true
+      def initialize(id:, effects:, rule: nil)
+        @id = id.to_sym
+        @effects = effects.freeze
+        @rule = rule
+        freeze
+      end
+
+      # @param answers_hash [Hash] step_id => value context for rule evaluation
+      # @return [Boolean]
+      def applicable?(answers_hash)
+        @rule.nil? || @rule.evaluate(answers_hash)
+      end
+
+      # @return [Boolean] whether anything survives JSON serialization
+      def serializable?
+        @effects.any?(&:serializable?)
+      end
+
+      # @return [Hash] wire format; run blocks are stripped
+      def to_h
+        hash = { "id" => @id.to_s }
+        hash["if"] = @rule.to_h if @rule
+        hash["effects"] = @effects.select(&:serializable?).map(&:to_h)
+        hash
+      end
+
+      # @param hash [Hash] string or symbol keys
+      # @return [Action]
+      def self.from_h(hash)
+        id = hash["id"] || hash[:id]
+        rule_data = hash["if"] || hash[:if]
+        effects_data = hash["effects"] || hash[:effects] || []
+
+        effects = effects_data.map do |effect_hash|
+          type = effect_hash["type"] || effect_hash[:type]
+          Actions.lookup(type).from_h(effect_hash)
+        end
+
+        new(
+          id:      id.to_sym,
+          effects: effects,
+          rule:    rule_data ? Rules::Base.from_h(rule_data) : nil
+        )
+      end
+    end
+  end
+end

data/lib/inquirex/actions/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Actions
+    # Abstract base for action effects — the executable units inside an
+    # `action` block. Subclasses implement #call and, when serializable,
+    # #to_h / .from_h following the same round-trip pattern as Rules::Base.
+    #
+    # Effects that wrap Ruby procs (Actions::Custom) return false from
+    # #serializable? and are stripped from JSON, consistent with how
+    # lambdas are handled everywhere else in Inquirex.
+    class Base
+      # Executes the effect. Email-building effects append Mail::Message
+      # objects to the outbox; custom effects may do anything server-side.
+      #
+      # @param answers [Answers] completed answers
+      # @param outbox [Outbox] collector for built messages
+      # @return [void]
+      def call(answers, outbox)
+        raise NotImplementedError, "#{self.class}#call must be implemented"
+      end
+
+      # @return [Boolean] whether this effect survives JSON serialization
+      def serializable? = true
+
+      # Hook for effects that must be checked against the definition carrying
+      # them (e.g. Webhook vs allowed_domains). Runs inside
+      # Definition#validate!, which both DSL-built and JSON-rehydrated
+      # definitions pass through — so violations fail at load time.
+      #
+      # @param _definition [Definition]
+      # @raise [Errors::DefinitionError] on violation
+      def validate_against(_definition); end
+
+      # @return [Hash]
+      def to_h
+        raise NotImplementedError, "#{self.class}#to_h must be implemented"
+      end
+    end
+  end
+end

data/lib/inquirex/actions/custom.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Actions
+    # Escape-hatch effect wrapping an arbitrary Ruby block, declared in the
+    # DSL as `run { |answers, outbox| ... }`. Full language power — build a
+    # Mail::Message by hand with outbox.add_message, call a service, record
+    # metrics — at the cost of serialization: like every lambda in Inquirex,
+    # the block is stripped from JSON and exists only in Ruby-authored
+    # definitions.
+    class Custom < Base
+      # @param block [Proc] receives (answers, outbox)
+      def initialize(block)
+        super()
+        @block = block
+        freeze
+      end
+
+      # Invokes the wrapped block with the collected answers and the outbox.
+      #
+      # @param answers [Answers] completed answers
+      # @param outbox [Outbox] collector for messages the block may build
+      # @return [Object] whatever the block returns (recorded, not interpreted)
+      def call(answers, outbox)
+        @block.call(answers, outbox)
+      end
+
+      def serializable? = false
+    end
+  end
+end

data/lib/inquirex/actions/outbox.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Actions
+    # Collected output of running a definition's actions: the Mail::Message
+    # objects built by send_email effects, plus a per-execution result trail.
+    #
+    # The outbox is attached to Answers#outbox and is intentionally excluded
+    # from Answers serialization — mail objects never leak into persisted
+    # answer data. Delivery is the host application's job:
+    #
+    #   answers.outbox.each do |message|
+    #     ActionMailer::Base.wrap_delivery_behavior(message)
+    #     message.deliver
+    #   end
+    class Outbox
+      include Enumerable
+
+      # One entry per effect execution (or per skipped action).
+      # status is :ok, :skipped (action rule was false), or :failed.
+      Result = Data.define(:action_id, :status, :error)
+
+      attr_reader :messages, :results
+
+      def initialize
+        @messages = []
+        @results = []
+      end
+
+      # @param mail [Mail::Message]
+      # @return [Mail::Message]
+      def add_message(mail)
+        @messages << mail
+        mail
+      end
+
+      # @param action_id [Symbol]
+      # @param status [Symbol] :ok, :skipped, or :failed
+      # @param error [StandardError, nil]
+      def record(action_id, status, error: nil)
+        @results << Result.new(action_id:, status:, error:)
+      end
+
+      # Iterates over built Mail::Message objects.
+      def each(&) = @messages.each(&)
+
+      # @return [Integer] number of built messages
+      def size = @messages.size
+
+      # @return [Boolean]
+      def empty? = @messages.empty?
+
+      # @return [Array<Result>] executions that raised
+      def failures = @results.select { |result| result.status == :failed }
+    end
+  end
+end

data/lib/inquirex/actions/runner.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Actions
+    # Executes a definition's actions against completed answers, in
+    # declaration order, populating Answers#outbox with built messages and a
+    # result trail.
+    #
+    # Deliberately separate from the Engine: in the cross-site architecture
+    # the frontend collects answers and a different server process
+    # post-processes them, so the runner is a pure function of
+    # (definition, answers) — which also makes rebuilding messages inside a
+    # background job trivial.
+    #
+    # A failing effect records a :failed result and never aborts the other
+    # actions; the host inspects outbox.failures and decides what to do.
+    class Runner
+      # @param definition [Definition]
+      def initialize(definition)
+        @definition = definition
+      end
+
+      # @param answers [Answers, Hash] completed answers (a Hash is wrapped)
+      # @return [Answers] the (possibly wrapped) answers with #outbox populated
+      def call(answers)
+        answers = Answers.new(answers) unless answers.is_a?(Answers)
+        context = answers.to_h
+
+        @definition.actions.each do |action|
+          unless action.applicable?(context)
+            answers.outbox.record(action.id, :skipped)
+            next
+          end
+          execute(action, answers)
+        end
+
+        answers
+      end
+
+      private
+
+      def execute(action, answers)
+        action.effects.each do |effect|
+          effect.call(answers, answers.outbox)
+          answers.outbox.record(action.id, :ok)
+        rescue StandardError => e
+          answers.outbox.record(action.id, :failed, error: e)
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/actions/send_email.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Actions
+    # Declarative email effect. Builds a Mail::Message (the object ActionMailer
+    # itself wraps) from {{field}} templates and appends it to the outbox.
+    # Nothing is delivered — the host application sends the messages.
+    #
+    # Scalar fields (to, from, cc, bcc, reply_to, subject) and the text body
+    # render values verbatim; the html body HTML-escapes every interpolated
+    # value automatically. Both bodies given => multipart/alternative.
+    #
+    # Bodies accept an inline template String or { file: "path" }, which is
+    # read once at definition time and inlined — a definition rehydrated from
+    # JSON never touches the filesystem.
+    #
+    # Images: reference external URLs in the html body. Attachments are
+    # deliberately unsupported.
+    #
+    # The mail gem is a soft dependency, required only when a message is
+    # actually built. Rails hosts always have it (ActionMailer depends on it).
+    class SendEmail < Base
+      # Scalar header fields rendered verbatim via Template.render_text in #to_mail and #to_h.
+      SCALAR_FIELDS = %i[to from cc bcc reply_to subject].freeze
+
+      # @return [String] required recipient / subject templates ({{field}} placeholders allowed)
+      attr_reader :to, :subject
+
+      # @return [String, nil] optional address templates ({{field}} placeholders allowed)
+      attr_reader :from, :cc, :bcc, :reply_to
+
+      # @return [String, nil] body template, inlined at definition time when { file: } was given
+      attr_reader :text, :html
+
+      # @return [Hash{String => String}] extra headers (values support {{field}})
+      attr_reader :headers
+
+      # @param to [String] recipient template (required)
+      # @param subject [String] subject template (required)
+      # @param text [String, Hash, nil] plain-text body template or { file: }
+      # @param html [String, Hash, nil] HTML body template or { file: }
+      # @param headers [Hash] extra headers (values support {{field}})
+      # @raise [Errors::DefinitionError] when required fields are missing
+      def initialize(to:, subject:, from: nil, cc: nil, bcc: nil, reply_to: nil,
+        text: nil, html: nil, headers: {})
+        super()
+        @to = to
+        @from = from
+        @cc = cc
+        @bcc = bcc
+        @reply_to = reply_to
+        @subject = subject
+        @text = resolve_body(text)
+        @html = resolve_body(html)
+        @headers = headers.transform_keys(&:to_s).freeze
+        validate!
+        freeze
+      end
+
+      # Builds the message and appends it to the outbox.
+      #
+      # @param answers [Answers] completed answers
+      # @param outbox [Outbox] receives the built Mail::Message
+      # @return [void]
+      def call(answers, outbox)
+        outbox.add_message(to_mail(answers))
+      end
+
+      # Builds a Mail::Message from the templates and the given answers.
+      # Pure function — safe to call from a background job to rebuild
+      # messages from persisted answers.
+      #
+      # @param answers [Answers]
+      # @return [Mail::Message]
+      def to_mail(answers)
+        require_mail!
+        mail = ::Mail.new
+        SCALAR_FIELDS.each do |field|
+          value = public_send(field)
+          mail.public_send(:"#{field}=", Template.render_text(value, answers)) if value
+        end
+        @headers.each { |name, value| mail.header[name] = Template.render_text(value.to_s, answers) }
+        attach_bodies(mail, answers)
+        mail
+      end
+
+      # @return [Hash] wire format, same shape .from_h accepts
+      def to_h
+        hash = { "type" => "send_email" }
+        SCALAR_FIELDS.each do |field|
+          value = public_send(field)
+          hash[field.to_s] = value if value
+        end
+        hash["text"] = @text if @text
+        hash["html"] = @html if @html
+        hash["headers"] = @headers unless @headers.empty?
+        hash
+      end
+
+      # @param hash [Hash] string or symbol keys
+      # @return [SendEmail]
+      def self.from_h(hash)
+        fetch = ->(key) { hash[key.to_s] || hash[key.to_sym] }
+        new(
+          to:       fetch.call(:to),
+          from:     fetch.call(:from),
+          cc:       fetch.call(:cc),
+          bcc:      fetch.call(:bcc),
+          reply_to: fetch.call(:reply_to),
+          subject:  fetch.call(:subject),
+          text:     fetch.call(:text),
+          html:     fetch.call(:html),
+          headers:  fetch.call(:headers) || {}
+        )
+      end
+
+      private
+
+      def attach_bodies(mail, answers)
+        text = @text && Template.render_text(@text, answers)
+        html = @html && Template.render_html(@html, answers)
+        if text && html
+          mail.text_part = build_part("text/plain; charset=UTF-8", text)
+          mail.html_part = build_part("text/html; charset=UTF-8", html)
+        elsif html
+          mail.content_type = "text/html; charset=UTF-8"
+          mail.body = html
+        else
+          mail.body = text
+        end
+      end
+
+      def build_part(content_type, body)
+        part = ::Mail::Part.new
+        part.content_type = content_type
+        part.body = body
+        part
+      end
+
+      # Inline template string, or { file: "path" } read once at definition time.
+      def resolve_body(value)
+        return value if value.nil? || value.is_a?(String)
+
+        path = value.is_a?(Hash) && (value[:file] || value["file"])
+        return File.read(File.expand_path(path)) if path.is_a?(String)
+
+        raise Errors::DefinitionError,
+          "send_email body must be a template String or { file: \"path\" }, got #{value.inspect}"
+      end
+
+      def validate!
+        raise Errors::DefinitionError, "send_email requires to:" if blank?(@to)
+        raise Errors::DefinitionError, "send_email requires subject:" if blank?(@subject)
+        return unless @text.nil? && @html.nil?
+
+        raise Errors::DefinitionError, "send_email requires a text: or html: body"
+      end
+
+      def blank?(value) = value.nil? || value.to_s.strip.empty?
+
+      def require_mail!
+        return if defined?(::Mail)
+
+        require "mail"
+      rescue LoadError
+        raise Errors::ActionError,
+          "send_email requires the mail gem — add `gem \"mail\"` to your Gemfile " \
+          "(Rails applications already have it via ActionMailer)"
+      end
+    end
+
+    register(:send_email, SendEmail)
+  end
+end