inquirex 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ce3e2bcf0a91cdba8c83abd9af02807b25462ff878762f0a0114372554dfe84
-  data.tar.gz: 017b1f51f0641f57aecd2a9c84fb3c4fb5e39b6252ac1a4de4f9735bd79d7837
+  metadata.gz: f99f7adba97c905c55490b57467fe062251719bbb98d698fe49e6dd04360fcf7
+  data.tar.gz: 2c6850590153b96ee376ddaa0314c2de3cf729f6ea2d7c8f3d0ccb20d2359683
 SHA512:
-  metadata.gz: a426a31f57e7c3ef4e7bdeb2cd288da6fb66717436c167e0f3a03e808706f9525ea3c687055da32b3413015a80882524f88b05c6d01ea06dc5875dfb96f93521
-  data.tar.gz: 9be96813505bf0ce8a0d5eed1a3e775dd0a08b8b54a5484993abe9119663323dd8075aba8fb74d3aebeed63c82370ee04fff6488a2b72d13bfcda0a47d38b525
+  metadata.gz: 18b95d28461f971551997bb177c6ead5c4165562f1d627460d58656440a0884bf0972eef2d97a31e3883f34720349be82e24e2fa567b7181eea0f14361182355
+  data.tar.gz: ed93da41fe8d2f66098b0165224e472d794d6f7ab9313dd8ec9a8a80b0d299ef5623d957361d83a27680b1ce3c025dd294fc6690c855c02a32df90348726718c

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [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

@@ -466,6 +466,120 @@ 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 +597,11 @@ 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/docs/badges/coverage_badge.svg

@@ -15,7 +15,7 @@
   <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
     <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
     <text x="31.5" y="14">coverage</text>
-    <text x="80" y="15" fill="#010101" fill-opacity=".3">95%</text>
-    <text x="80" y="14">95%</text>
+    <text x="80" y="15" fill="#010101" fill-opacity=".3">96%</text>
+    <text x="80" y="14">96%</text>
   </g>
 </svg>

data/examples/03_send_email_actions.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 03: Post-completion actions building emails into the outbox.
+#
+# The `action` verb runs server-side after the flow finishes. send_email
+# builds Mail::Message objects — nothing is delivered here; a host Rails app
+# would iterate answers.outbox and deliver via its own ActionMailer config.
+#
+# Run:
+#   bundle exec ruby examples/03_send_email_actions.rb
+
+require "bundler/setup"
+require "inquirex"
+
+DEFINITION = Inquirex.define id: "lead-intake", version: "1.0.0" do
+  # Egress allowlist: webhook effects may only POST to these hosts.
+  allowed_domains "*.agentica.group"
+
+  meta title: "Lead Intake", subtitle: "Tell us about your project"
+  start :name
+
+  ask :name do
+    type :string
+    question "What is your name?"
+    transition to: :email
+  end
+
+  ask :email do
+    type :email
+    question "Where can we reach you? (leave blank to skip the receipt)"
+    transition to: :budget
+  end
+
+  ask :budget do
+    type :currency
+    question "What is your approximate budget?"
+  end
+
+  # Sent only when the visitor left an email address.
+  action :client_receipt, if: not_empty(:email) do
+    send_email to:      "{{email}}",
+      from:    "forms@agentica.group",
+      subject: "Thanks {{name}} — we got your inquiry",
+      text:    <<~TEXT,
+        Hi {{name}},
+
+        We received your answers and will reply within one business day.
+
+        {{answers_summary}}
+      TEXT
+      html:    <<~HTML
+        <p>Hi {{name}},</p>
+        <p>We received your answers and will reply within one business day.</p>
+        {{answers_summary}}
+      HTML
+  end
+
+  # Always notify the site owner, and demonstrate the Ruby escape hatch.
+  action :admin_alert do
+    send_email to: "owner@agentica.group",
+      from: "forms@agentica.group",
+      subject: "New lead: {{name}} (budget {{budget}})",
+      html: "{{answers_summary}}"
+    run { |answers, _outbox| puts ">> run{} saw budget: #{answers.budget}" }
+  end
+
+  # Webhook to an allowed_domains host. Gated by an always-false rule so this
+  # example runs offline — it records :skipped instead of POSTing. Drop the
+  # if: to exercise it for real.
+  action :crm_push, if: equals(:name, "__network_demo__") do
+    webhook url: "https://hooks.agentica.group/inquirex",
+      headers: { "X-Api-Key" => "demo" }
+  end
+end
+
+answers = Inquirex::Actions.run(
+  DEFINITION,
+  name:   "Ada Lovelace",
+  email:  "ada@lovelace.io",
+  budget: 12_500.00
+)
+
+puts "Built #{answers.outbox.size} message(s):"
+answers.outbox.each do |mail|
+  puts "-" * 60
+  puts "To:      #{mail.to.join(", ")}"
+  puts "Subject: #{mail.subject}"
+  puts "Parts:   #{mail.multipart? ? "text + html" : mail.content_type}"
+end
+
+puts "-" * 60
+puts "Results: #{answers.outbox.results.map { |r| "#{r.action_id}=#{r.status}" }.join(", ")}"
+
+# The definition (rules and all) round-trips through JSON — run{} is stripped:
+restored = Inquirex::Definition.from_json(DEFINITION.to_json)
+puts "Actions after JSON round-trip: #{restored.actions.map(&:id).inspect}"

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