inquirex 0.4.1 → 0.6.0

data/lib/inquirex/actions/webhook.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Inquirex
+  module Actions
+    # Declarative webhook effect: POSTs the completed answers as a JSON
+    # envelope ({"answers" => {...}}) to a statically-declared URL.
+    #
+    # Security posture — the URL must be auditable and its host covered by the
+    # definition's allowed_domains declaration:
+    #
+    # - the URL is a literal string; {{field}} templates are rejected so the
+    #   destination host can never depend on user input
+    # - https only; plain http is permitted solely for localhost development
+    # - userinfo (https://user@host/) is rejected
+    # - redirects are not followed (Net::HTTP does not follow them)
+    # - the host check runs in Definition#validate!, which every definition
+    #   passes through — including JSON-rehydrated ones, so a tampered URL
+    #   fails at load time, before anything executes
+    #
+    # A non-2xx response raises Errors::ActionError, which the Runner records
+    # as a :failed result without blocking other actions.
+    class Webhook < Base
+      # Default open/read timeout in seconds for the webhook POST.
+      DEFAULT_TIMEOUT = 10
+      # Hosts for which plain http is tolerated (local development only).
+      LOCAL_HOSTS = %w[localhost 127.0.0.1 ::1 [::1]].freeze
+
+      attr_reader :url, :headers, :timeout
+
+      # @param url [String] literal https URL (no {{field}} templates)
+      # @param headers [Hash] extra request headers (literal values)
+      # @param timeout [Integer] open/read timeout in seconds
+      def initialize(url:, headers: {}, timeout: DEFAULT_TIMEOUT)
+        super()
+        @url = url.to_s
+        @headers = headers.transform_keys(&:to_s).transform_values(&:to_s).freeze
+        @timeout = timeout.to_i
+        @uri = parse_and_check!(@url)
+        freeze
+      end
+
+      # @return [String] lowercase host of the webhook URL
+      def host = @uri.host.downcase
+
+      # POSTs the answers envelope to the declared URL.
+      #
+      # @param answers [Answers] completed answers
+      # @param _outbox [Outbox] unused — webhooks build no messages
+      # @return [Net::HTTPResponse] the 2xx response
+      # @raise [Errors::ActionError] when the endpoint responds non-2xx
+      def call(answers, _outbox)
+        require "net/http"
+        response = post(answers)
+        code = response.code.to_i
+        return response if (200..299).cover?(code)
+
+        raise Errors::ActionError, "webhook #{host} responded with HTTP #{response.code}"
+      end
+
+      # Enforced from Definition#validate!.
+      #
+      # @param definition [Definition] owning definition, source of allowed_domains
+      # @return [void]
+      # @raise [Errors::DefinitionError] when the host is not allowlisted
+      def validate_against(definition)
+        return if definition.allowed_host?(host)
+
+        raise Errors::DefinitionError,
+          "webhook url host #{host.inspect} is not covered by allowed_domains " \
+          "#{definition.allowed_domains.inspect} — declare it at the top of the definition"
+      end
+
+      # @return [Hash] wire format, same shape .from_h accepts
+      def to_h
+        hash = { "type" => "webhook", "url" => @url }
+        hash["headers"] = @headers unless @headers.empty?
+        hash["timeout"] = @timeout unless @timeout == DEFAULT_TIMEOUT
+        hash
+      end
+
+      # @param hash [Hash] string or symbol keys
+      # @return [Webhook]
+      def self.from_h(hash)
+        fetch = ->(key) { hash[key.to_s] || hash[key.to_sym] }
+        new(
+          url:     fetch.call(:url),
+          headers: fetch.call(:headers) || {},
+          timeout: fetch.call(:timeout) || DEFAULT_TIMEOUT
+        )
+      end
+
+      private
+
+      def post(answers)
+        request = Net::HTTP::Post.new(@uri)
+        request["Content-Type"] = "application/json"
+        @headers.each { |name, value| request[name] = value }
+        request.body = JSON.generate("answers" => answers.to_h)
+
+        Net::HTTP.start(
+          @uri.host,
+          @uri.port,
+          use_ssl:      @uri.scheme == "https",
+          open_timeout: @timeout,
+          read_timeout: @timeout
+        ) { |http| http.request(request) }
+      end
+
+      def parse_and_check!(url)
+        if url.include?("{{")
+          raise Errors::DefinitionError,
+            "webhook url does not support {{field}} templates — the destination must be static"
+        end
+
+        uri = parse(url)
+        raise Errors::DefinitionError, "webhook url must be http(s): #{url.inspect}" unless uri.is_a?(URI::HTTP)
+        raise Errors::DefinitionError, "webhook url must include a host: #{url.inspect}" if uri.host.to_s.empty?
+        raise Errors::DefinitionError, "webhook url must not include userinfo: #{url.inspect}" if uri.userinfo
+
+        if uri.scheme == "http" && !LOCAL_HOSTS.include?(uri.host.downcase)
+          raise Errors::DefinitionError,
+            "webhook url must use https (plain http is allowed only for localhost): #{url.inspect}"
+        end
+
+        uri
+      end
+
+      def parse(url)
+        URI.parse(url)
+      rescue URI::InvalidURIError => e
+        raise Errors::DefinitionError, "webhook url is not a valid URL: #{e.message}"
+      end
+    end
+
+    register(:webhook, Webhook)
+  end
+end

data/lib/inquirex/actions.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Inquirex
+  # Post-completion actions: named side-effect declarations that run
+  # server-side after a flow finishes, with access to the collected answers.
+  #
+  # The DSL word `action` groups one or more *effects* (send_email, run, ...).
+  # Effects are looked up in a registry keyed by their DSL verb, so new effect
+  # types — a webhook, a save_record in inquirex-rails — plug in without core
+  # changes: register the class and it gains both the DSL word and JSON wire
+  # support.
+  #
+  #   Inquirex::Actions.register(:webhook, MyGem::WebhookEffect)
+  #
+  # Actions never deliver anything themselves. send_email builds Mail::Message
+  # objects into Answers#outbox; the host application decides how to send them.
+  module Actions
+    @registry = {}
+
+    class << self
+      # Registers an effect class under a DSL verb name.
+      #
+      # @param type [Symbol] DSL verb (e.g. :send_email)
+      # @param klass [Class] an Actions::Base subclass
+      def register(type, klass)
+        @registry[type.to_sym] = klass
+      end
+
+      # @param type [Symbol, String]
+      # @return [Boolean]
+      def registered?(type)
+        @registry.key?(type.to_sym)
+      end
+
+      # @param type [Symbol, String]
+      # @return [Class]
+      # @raise [Errors::SerializationError] for unknown effect types
+      def lookup(type)
+        @registry.fetch(type.to_sym) do
+          raise Errors::SerializationError, "Unknown action effect type: #{type.inspect}"
+        end
+      end
+
+      # @return [Array<Symbol>] registered effect verbs
+      def types = @registry.keys
+
+      # Runs all of the definition's actions against the given answers.
+      #
+      # @param definition [Definition]
+      # @param answers [Answers, Hash]
+      # @return [Answers] with #outbox populated
+      def run(definition, answers)
+        Runner.new(definition).call(answers)
+      end
+    end
+  end
+end

data/lib/inquirex/answers.rb

@@ -84,10 +84,22 @@ module Inquirex
     end
 
     # Number of top-level answer keys.
+    #
+    # @return [Integer]
     def size
       @data.size
     end
 
+    # Mail::Message objects (and result trail) built by post-completion
+    # actions. Deliberately excluded from #to_h, #to_flat_h, #to_json and
+    # #== — the outbox rides alongside the answer data, never inside it.
+    # Delivery is the host application's responsibility.
+    #
+    # @return [Actions::Outbox]
+    def outbox
+      @outbox ||= Actions::Outbox.new
+    end
+
     # Merge another hash or Answers into this one (returns new Answers instance).
     #
     # @param other [Hash, Answers]
@@ -97,6 +109,7 @@ module Inquirex
       Answers.new(@data.merge(other_data))
     end
 
+    # @return [String] debug representation including the underlying hash
     def inspect
       "#<Inquirex::Answers #{@data.inspect}>"
     end

data/lib/inquirex/completion_metadata.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "ostruct"
+require "json"
+
+module Inquirex
+  # An OpenStruct describing how a flow reached completion: which rendering
+  # engine collected the answers, and any environment details that renderer
+  # chose to attach (host uname, user, IP addresses, terminal, ...).
+  #
+  # Only :engine and :engine_version are required members — enforced at
+  # construction. Everything else is free-form OpenStruct behavior: unset
+  # members read as nil, assignment creates members, nested OpenStructs
+  # (e.g. uname) are welcome.
+  #
+  # @example
+  #   meta = Inquirex::CompletionMetadata.new(
+  #     engine: "inquirex-tty", engine_version: "0.5.0",
+  #     uname: OpenStruct.new(Etc.uname)
+  #   )
+  #   meta.engine          # => "inquirex-tty"
+  #   meta.uname.machine   # => "arm64"
+  #   meta.hostname        # => nil (unset members read as nil)
+  #   meta.to_h            # => plain nested Hash, JSON-ready
+  class CompletionMetadata < OpenStruct
+    # Members that must be provided at construction; everything else is optional.
+    REQUIRED_MEMBERS = %i[engine engine_version].freeze
+
+    # Exists solely to make :engine and :engine_version required keywords —
+    # OpenStruct itself would accept anything.
+    #
+    # @param engine [String] rendering front-end name (e.g. "inquirex-tty")
+    # @param engine_version [String] rendering front-end version
+    # @param extra [Hash] any additional, optional members
+    def initialize(engine:, engine_version:, **extra) # rubocop:disable Lint/UselessMethodDefinition
+      super
+    end
+
+    # Rebuilds an instance from a hash (e.g. persisted engine state after a
+    # JSON round-trip). Keys may be strings or symbols; nested hashes come
+    # back as OpenStructs so dot-access survives the round-trip.
+    #
+    # @param hash [Hash, nil]
+    # @return [CompletionMetadata, nil] nil when hash is nil or empty
+    # @raise [ArgumentError] when :engine or :engine_version is missing
+    def self.from_h(hash)
+      return nil if hash.nil? || hash.empty?
+
+      members = hash.to_h { |k, v| [k.to_sym, v.is_a?(Hash) ? OpenStruct.new(v) : v] }
+      new(**members)
+    end
+
+    # OpenStruct#to_h is shallow; deep-convert nested OpenStructs (uname et
+    # al.) so state serialization and JSON output stay plain data.
+    #
+    # @return [Hash]
+    def to_h
+      deep_plain(super)
+    end
+
+    # @return [String] JSON representation
+    def to_json(*)
+      JSON.generate(to_h)
+    end
+
+    # @return [String] debug representation of the deep-plain member hash
+    def inspect
+      "#<Inquirex::CompletionMetadata #{to_h.inspect}>"
+    end
+
+    private
+
+    def deep_plain(value)
+      case value
+      when OpenStruct then deep_plain(value.to_h)
+      when Hash       then value.transform_values { |v| deep_plain(v) }
+      when Array      then value.map { |v| deep_plain(v) }
+      else value
+      end
+    end
+  end
+end

data/lib/inquirex/definition.rb

@@ -13,7 +13,14 @@ module Inquirex
   # @attr_reader start_step_id [Symbol] id of the first step in the flow
   # @attr_reader steps [Hash<Symbol, Node>] frozen map of step id => node
   class Definition
-    attr_reader :id, :version, :meta, :start_step_id, :steps, :accumulators
+    attr_reader :id,
+      :version,
+      :meta,
+      :start_step_id,
+      :steps,
+      :accumulators,
+      :actions,
+      :allowed_domains
 
     # @param start_step_id [Symbol] id of the initial step
     # @param nodes [Hash<Symbol, Node>] all steps keyed by id
@@ -21,14 +28,20 @@ module Inquirex
     # @param version [String] semver
     # @param meta [Hash] frontend metadata
     # @param accumulators [Hash<Symbol, Accumulator>] named running totals
+    # @param actions [Array<Actions::Action>] post-completion actions, in order
+    # @param allowed_domains [Array<String>] hosts outbound effects (webhook)
+    #   may send answers to; "example.com" exact, "*.example.com" subdomains
     # @raise [Errors::DefinitionError] if start_step_id is not present in nodes
-    def initialize(start_step_id:, nodes:, id: nil, version: "1.0.0", meta: {}, accumulators: {})
+    def initialize(start_step_id:, nodes:, id: nil, version: "1.0.0", meta: {},
+      accumulators: {}, actions: [], allowed_domains: [])
       @id = id
       @version = version
       @meta = meta.freeze
       @start_step_id = start_step_id.to_sym
       @steps = nodes.freeze
       @accumulators = accumulators.freeze
+      @actions = actions.freeze
+      @allowed_domains = normalize_domains(allowed_domains)
       validate!
       freeze
     end
@@ -50,6 +63,25 @@ module Inquirex
       @steps.keys
     end
 
+    # Whether a host is covered by the allowed_domains declaration.
+    # "example.com" matches that host exactly; "*.example.com" matches any
+    # subdomain but not the apex. Matching is case-insensitive; an empty
+    # allowlist allows nothing.
+    #
+    # @example With allowed_domains ["*.example.com"]
+    #   definition.allowed_host?("api.example.com") # => true
+    #   definition.allowed_host?("API.EXAMPLE.COM") # => true (case-insensitive)
+    #   definition.allowed_host?("example.com")     # => false (wildcard excludes the apex)
+    #
+    # @param host [String]
+    # @return [Boolean]
+    def allowed_host?(host)
+      target = host.to_s.downcase
+      @allowed_domains.any? do |entry|
+        entry.start_with?("*.") ? target.end_with?(entry[1..]) : target == entry
+      end
+    end
+
     # Serializes the definition to a JSON string.
     # Lambdas (default procs, compute blocks) are silently stripped.
     #
@@ -66,6 +98,7 @@ module Inquirex
       hash["id"] = @id if @id
       hash["version"] = @version
       hash["meta"] = @meta unless @meta.empty?
+      hash["allowed_domains"] = @allowed_domains unless @allowed_domains.empty?
       hash["start"] = @start_step_id.to_s
       unless @accumulators.empty?
         hash["accumulators"] = @accumulators.each_with_object({}) do |(name, acc), h|
@@ -73,6 +106,8 @@ module Inquirex
         end
       end
       hash["steps"] = @steps.transform_keys(&:to_s).transform_values(&:to_h)
+      serializable_actions = @actions.select(&:serializable?)
+      hash["actions"] = serializable_actions.map(&:to_h) unless serializable_actions.empty?
       hash
     end
 
@@ -97,6 +132,8 @@ module Inquirex
       start = hash["start"] || hash[:start]
       steps_data = hash["steps"] || hash[:steps] || {}
       acc_data = hash["accumulators"] || hash[:accumulators] || {}
+      actions_data = hash["actions"] || hash[:actions] || []
+      domains = hash["allowed_domains"] || hash[:allowed_domains] || []
 
       nodes = steps_data.each_with_object({}) do |(step_id, step_hash), acc|
         sym_id = step_id.to_sym
@@ -108,15 +145,40 @@ module Inquirex
         h[sym] = Accumulator.from_h(sym, entry)
       end
 
-      new(start_step_id: start, nodes:, id:, version:, meta:, accumulators:)
+      actions = actions_data.map { |entry| Actions::Action.from_h(entry) }
+
+      new(start_step_id: start,
+        nodes:,
+        id:,
+        version:,
+        meta:,
+        accumulators:,
+        actions:,
+        allowed_domains: domains)
     end
 
     private
 
     def validate!
-      return if @steps.key?(@start_step_id)
+      unless @steps.key?(@start_step_id)
+        raise Errors::DefinitionError, "Start step #{@start_step_id.inspect} not found in steps"
+      end
 
-      raise Errors::DefinitionError, "Start step #{@start_step_id.inspect} not found in steps"
+      @actions.each do |action|
+        action.effects.each { |effect| effect.validate_against(self) }
+      end
+    end
+
+    def normalize_domains(domains)
+      domains.map do |entry|
+        domain = entry.to_s.strip.downcase
+        if domain.empty? || domain == "*" || domain.match?(%r{[/\s:@]})
+          raise Errors::DefinitionError,
+            "allowed_domains entries must be bare domains like \"example.com\" " \
+            "or \"*.example.com\", got #{entry.inspect}"
+        end
+        domain
+      end.freeze
     end
   end
 end

data/lib/inquirex/dsl/action_builder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module DSL
+    # Builds an Actions::Action from an `action` DSL block. Every effect verb
+    # registered in Inquirex::Actions (send_email, plus anything host gems
+    # register) is available as a method automatically; `run` wraps arbitrary
+    # Ruby in an Actions::Custom effect.
+    #
+    #   action :admin_alert do
+    #     send_email to: "admin@example.com", subject: "New lead: {{name}}",
+    #                html: "{{answers_summary}}"
+    #     run { |answers, outbox| Metrics.count(:lead, answers.to_flat_h) }
+    #   end
+    class ActionBuilder
+      def initialize
+        @effects = []
+      end
+
+      # Escape hatch: arbitrary server-side Ruby. Stripped from JSON.
+      #
+      # @yield [answers, outbox]
+      def run(&block)
+        raise Errors::DefinitionError, "run requires a block" unless block
+
+        @effects << Actions::Custom.new(block)
+      end
+
+      # Registered effect verbs (send_email, ...) resolve dynamically so that
+      # newly registered effect types become DSL words without core changes.
+      def method_missing(name, *args, **params, &)
+        return super unless Actions.registered?(name)
+
+        raise Errors::DefinitionError, "#{name} takes keyword arguments only" unless args.empty?
+
+        @effects << Actions.lookup(name).new(**params)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        Actions.registered?(name) || super
+      end
+
+      # @param id [Symbol]
+      # @param rule [Rules::Base, nil]
+      # @return [Actions::Action]
+      def build(id, rule: nil)
+        raise Errors::DefinitionError, "action #{id.inspect} declares no effects" if @effects.empty?
+
+        Actions::Action.new(id:, effects: @effects, rule:)
+      end
+    end
+  end
+end

data/lib/inquirex/dsl/flow_builder.rb

@@ -16,6 +16,18 @@ module Inquirex
         @nodes = {}
         @meta = {}
         @accumulators = {}
+        @actions = []
+        @allowed_domains = []
+      end
+
+      # Declares the domains outbound effects (webhook) may send answers to.
+      # Conventionally the first declaration in a definition, so the flow's
+      # egress surface is auditable at a glance. "example.com" matches that
+      # host exactly; "*.example.com" matches its subdomains.
+      #
+      # @param domains [Array<String>]
+      def allowed_domains(*domains)
+        @allowed_domains.concat(domains.flatten)
       end
 
       # Declares a named running total the flow accumulates into as answers come in.
@@ -104,6 +116,35 @@ module Inquirex
         add_step(id, :confirm, &)
       end
 
+      # Declares a named post-completion action: effects (send_email, run, ...)
+      # executed server-side after the flow finishes, with the collected
+      # answers. Runs in declaration order; gate with a serializable rule via
+      # the if: option.
+      #
+      # @example Email the collected answers when business income was selected
+      #   action :notify_sales, if: Rules::Contains.new(:income_types, "Business") do
+      #     send_email to: "sales@example.com",
+      #                subject: "New lead: {{name}}",
+      #                html: "{{answers_summary}}"
+      #   end
+      #
+      # @param id [Symbol] action identifier
+      # @param opts [Hash] only if: is recognized — a Rules::Base gate
+      # @yield block evaluated in ActionBuilder (send_email, run, ...)
+      def action(id, **opts, &block)
+        rule = opts.delete(:if)
+        raise Errors::DefinitionError, "Unknown action options: #{opts.keys.inspect}" unless opts.empty?
+
+        sym = id.to_sym
+        if @actions.any? { |a| a.id == sym }
+          raise Errors::DefinitionError, "Duplicate action id: #{sym.inspect}"
+        end
+
+        builder = ActionBuilder.new
+        builder.instance_eval(&block) if block
+        @actions << builder.build(sym, rule:)
+      end
+
       # Produces the frozen Definition.
       #
       # @return [Definition]
@@ -113,12 +154,14 @@ module Inquirex
         raise Errors::DefinitionError, "No steps defined" if @nodes.empty?
 
         Definition.new(
-          start_step_id: @start_step_id,
-          nodes:         @nodes,
-          id:            @flow_id,
-          version:       @flow_version,
-          meta:          @meta,
-          accumulators:  @accumulators
+          start_step_id:   @start_step_id,
+          nodes:           @nodes,
+          id:              @flow_id,
+          version:         @flow_version,
+          meta:            @meta,
+          accumulators:    @accumulators,
+          actions:         @actions,
+          allowed_domains: @allowed_domains
         )
       end
 

data/lib/inquirex/engine/state_serializer.rb

@@ -5,11 +5,13 @@ module Inquirex
     # Handles state serialization for Engine persistence (DB, session store, etc.).
     # Normalizes string-keyed hashes (from JSON round-trips) to symbol-keyed hashes.
     module StateSerializer
+      # Per-key normalizers applied by .symbolize_state; unlisted keys pass through unchanged.
       SYMBOLIZERS = {
-        current_step_id: ->(v) { v&.to_sym },
-        history:         ->(v) { Array(v).map { |e| e&.to_sym } },
-        answers:         ->(v) { symbolize_answers(v) },
-        totals:          ->(v) { symbolize_answers(v) }
+        current_step_id:     ->(v) { v&.to_sym },
+        history:             ->(v) { Array(v).map { |e| e&.to_sym } },
+        answers:             ->(v) { symbolize_answers(v) },
+        totals:              ->(v) { symbolize_answers(v) },
+        completion_metadata: ->(v) { symbolize_answers(v) }
       }.freeze
 
       # Normalizes a state hash so step ids and history entries are symbols.