inquirex 0.4.1 → 0.6.0

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

data/lib/inquirex/actions/template.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+
+module Inquirex
+  module Actions
+    # Renders {{field}} placeholders against collected answers.
+    #
+    # Placeholders are dot-notation keys resolved via Answers#to_flat_h
+    # ("{{email}}", "{{business.count}}"). The syntax is deliberately inert —
+    # no code execution — so flow definitions stored in a database can be
+    # rendered server-side safely and a visual editor can preview templates
+    # client-side. It matches the {{field}} placeholder convention used by
+    # inquirex-llm prompts.
+    #
+    # Rendering modes:
+    # - render_text — values inserted verbatim
+    # - render_html — every interpolated value is HTML-escaped
+    #
+    # The built-in {{answers_summary}} placeholder expands to all collected
+    # answers: "key: value" lines in text mode, a simple table in HTML mode.
+    # Unknown fields render as empty strings; array values join with ", ".
+    module Template
+      # Matches one {{field}} placeholder; capture 1 is the dot-notation key.
+      PLACEHOLDER = /\{\{\s*([\w.]+)\s*\}\}/
+      # Reserved placeholder key that expands to a summary of all collected answers.
+      SUMMARY_KEY = "answers_summary"
+
+      module_function
+
+      # @param string [String] template with {{field}} placeholders
+      # @param answers [Answers]
+      # @return [String]
+      def render_text(string, answers)
+        render(string, answers, html: false)
+      end
+
+      # @example Interpolated values are HTML-escaped
+      #   answers = Inquirex::Answers.new(name: "Bob & Sons")
+      #   Inquirex::Actions::Template.render_html("<p>{{name}}</p>", answers)
+      #   # => "<p>Bob &amp; Sons</p>"
+      #
+      # @param string [String] template with {{field}} placeholders
+      # @param answers [Answers]
+      # @return [String]
+      def render_html(string, answers)
+        render(string, answers, html: true)
+      end
+
+      # Shared implementation behind render_text and render_html.
+      #
+      # @param string [String] template with {{field}} placeholders
+      # @param answers [Answers]
+      # @param html [Boolean] whether to HTML-escape interpolated values
+      # @return [String]
+      def render(string, answers, html:)
+        flat = answers.to_flat_h
+        string.gsub(PLACEHOLDER) do
+          key = Regexp.last_match(1)
+          next(html ? summary_html(flat) : summary_text(flat)) if key == SUMMARY_KEY
+
+          value = format_value(flat[key])
+          html ? CGI.escapeHTML(value) : value
+        end
+      end
+
+      # Formats a single answer value for interpolation.
+      #
+      # @param value [Object] raw answer value (nil renders as "")
+      # @return [String] arrays joined with ", ", everything else via #to_s
+      def format_value(value)
+        value.is_a?(Array) ? value.join(", ") : value.to_s
+      end
+
+      # Expands {{answers_summary}} in text mode.
+      #
+      # @param flat [Hash{String => Object}] flat answers, dot-notation keys
+      # @return [String] one "key: value" line per answer
+      def summary_text(flat)
+        flat.map { |key, value| "#{key}: #{format_value(value)}" }.join("\n")
+      end
+
+      # Expands {{answers_summary}} in HTML mode.
+      #
+      # @param flat [Hash{String => Object}] flat answers, dot-notation keys
+      # @return [String] a simple HTML table with one row per answer, fully escaped
+      def summary_html(flat)
+        rows = flat.map do |key, value|
+          "<tr><th>#{CGI.escapeHTML(key)}</th><td>#{CGI.escapeHTML(format_value(value))}</td></tr>"
+        end
+        %(<table class="inquirex-answers">#{rows.join}</table>)
+      end
+    end
+  end
+end