mixin_bot 3.0.0 → 3.0.2

data/lib/mixin_bot/blaze/router.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module MixinBot
+  module Blaze
+    # Routes decoded Blaze envelopes to handler classes — the dispatch layer
+    # above {MixinBot::Blaze::Reactor}'s raw `blaze_handler` lambda contract.
+    #
+    # A router IS a handler: it answers #call with the decoded envelope Hash,
+    # so it plugs straight into the configured Blaze handler:
+    #
+    #   router = MixinBot::Blaze::Router.new do
+    #     on 'text', EchoHandler
+    #     on 'transfer', DepositHandler
+    #     on category: 'APP_CARD', handler: AppCardHandler
+    #     on action: 'CREATE_MESSAGE', handler: ->(message) { ... }
+    #   end
+    #
+    #   MixinBot.configure do
+    #     self.blaze_handler = router
+    #   end
+    #
+    # or per bot: MixinBot::Blaze::Router.new(api: MixinBot.bot(:shop)) { ... }
+    #
+    # Matching is first-registered-wins on the message category (aliases like
+    # 'text' normalize to PLAIN_TEXT; raw categories pass through verbatim) or
+    # on a Hash of conditions ({action:, category:}) that must all hold.
+    # Unmatched envelopes are logged and ignored.
+    #
+    # Handler exceptions are logged (:handler_error) and re-raised: the
+    # reactor owns containment (it logs and keeps the loop alive) and, under
+    # `ack_policy: :after_handler`, withholds the acknowledgement so a failed
+    # message is redelivered on reconnect. Swallowing here would turn that
+    # policy into at-most-once.
+    #
+    # Handlers are one of:
+    # - a Class with #initialize(message) + #call (see {Router::Base});
+    #   instantiated per message, so handlers stay stateless;
+    # - any object responding to #call(message) (proc, method, instance).
+    #
+    class Router
+      ##
+      # Decoded view of a Blaze envelope. Wraps the raw envelope Hash and the
+      # bot API client that dispatched it, exposing decoded message data and
+      # a reply helper over the HTTP message API (no WebSocket access).
+      #
+      class Message
+        # Categories whose data_base64 payload is JSON (everything but
+        # PLAIN_TEXT/PLAIN_POST, whose payloads are plain strings).
+        JSON_CATEGORIES = %w[
+          PLAIN_CONTACT
+          PLAIN_STICKER
+          PLAIN_LIVE
+          PLAIN_LOCATION
+          PLAIN_IMAGE
+          PLAIN_DATA
+          PLAIN_AUDIO
+          PLAIN_VIDEO
+          APP_CARD
+          APP_BUTTON_GROUP
+          SYSTEM_ACCOUNT_SNAPSHOT
+          MESSAGE_RECALL
+        ].freeze
+
+        attr_reader :raw
+
+        def initialize(raw, api:)
+          @raw = raw.is_a?(Hash) ? raw : {}
+          @api = api
+        end
+
+        def action
+          @raw['action']
+        end
+
+        # The envelope's message params Hash (empty when absent).
+        def params
+          data = @raw['data']
+          data.is_a?(Hash) ? data : {}
+        end
+
+        def category
+          params['category']
+        end
+
+        def conversation_id
+          params['conversation_id']
+        end
+
+        def recipient_id
+          params['recipient_id']
+        end
+
+        def representative_id
+          params['representative_id']
+        end
+
+        def message_id
+          params['message_id']
+        end
+
+        # The message's sender (inbound messages carry the sender in user_id).
+        def user_id
+          params['user_id']
+        end
+
+        def quote_message_id
+          params['quote_message_id']
+        end
+
+        ##
+        # The decoded message payload: the base64-decoded string for text-like
+        # categories, parsed JSON for structured ones. Decoded lazily, once.
+        #
+        def data
+          return @data if defined?(@data)
+
+          decoded = Base64.decode64(params['data_base64'].to_s)
+          @data = JSON_CATEGORIES.include?(category) ? parse_json(decoded) : decoded
+        end
+
+        ##
+        # Sends content back to the message's sender in its conversation over
+        # the HTTP message API. Supports PLAIN_TEXT (default) and PLAIN_POST;
+        # for anything richer, build params via the bound API (exposed by
+        # {Blaze::API helpers} on the api client) and send directly.
+        #
+        # @param content [String] text or post content
+        # @param category [String] 'PLAIN_TEXT' or 'PLAIN_POST'
+        #
+        def reply(content, category: 'PLAIN_TEXT')
+          options = { conversation_id:, recipient_id: user_id, data: content }
+          payload =
+            case category
+            when 'PLAIN_TEXT' then @api.plain_text(options)
+            when 'PLAIN_POST' then @api.plain_post(options)
+            else raise MixinBot::ArgumentError, "unsupported reply category #{category.inspect}"
+            end
+
+          @api.send_message(payload)
+        end
+
+        private
+
+        def parse_json(str)
+          JSON.parse(str)
+        rescue JSON::ParserError, EncodingError
+          str
+        end
+      end
+
+      ##
+      # Base class for message handlers: subclass, implement #handle, use
+      # #reply / #message. Instantiated per message by the router.
+      #
+      class Base
+        attr_reader :message
+
+        def initialize(message)
+          @message = message
+        end
+
+        def call
+          handle
+        end
+
+        def handle
+          raise NotImplementedError, "#{self.class} must implement #handle"
+        end
+
+        def reply(content, category: 'PLAIN_TEXT')
+          message.reply(content, category:)
+        end
+      end
+
+      # A compiled matcher paired with its handler.
+      Route = Struct.new(:matcher, :handler) do
+        def matches?(message)
+          matcher.call(message)
+        end
+      end
+
+      # Short aliases accepted by #on (in addition to raw categories, which
+      # pass through verbatim when they start with PLAIN_/SYSTEM_/APP_/
+      # MESSAGE_).
+      CATEGORY_ALIASES = {
+        'text' => 'PLAIN_TEXT',
+        'post' => 'PLAIN_POST',
+        'image' => 'PLAIN_IMAGE',
+        'data' => 'PLAIN_DATA',
+        'file' => 'PLAIN_DATA',
+        'sticker' => 'PLAIN_STICKER',
+        'contact' => 'PLAIN_CONTACT',
+        'audio' => 'PLAIN_AUDIO',
+        'video' => 'PLAIN_VIDEO',
+        'live' => 'PLAIN_LIVE',
+        'location' => 'PLAIN_LOCATION',
+        'transfer' => 'SYSTEM_ACCOUNT_SNAPSHOT',
+        'snapshot' => 'SYSTEM_ACCOUNT_SNAPSHOT',
+        'app_card' => 'APP_CARD',
+        'app_button_group' => 'APP_BUTTON_GROUP',
+        'buttons' => 'APP_BUTTON_GROUP',
+        'recall' => 'MESSAGE_RECALL'
+      }.freeze
+
+      attr_reader :api, :routes
+
+      ##
+      # @param api [MixinBot::API] bot client bound to this router; replies and
+      #   handler-side API calls use its credentials
+      # @param logger [#call, nil] called with (level, detail); defaults to
+      #   $stderr (same shape as MixinBot::Blaze::Reactor's logger)
+      # @yield the routing DSL (see #on)
+      #
+      def initialize(api: MixinBot.api, logger: nil, &)
+        @api = api
+        @routes = []
+        @logger = logger || ->(level, detail) { warn "[mixin_blaze] #{level}: #{detail}" }
+        instance_exec(&) if block_given?
+      end
+
+      ##
+      # Registers a route. Matchers:
+      # - a category alias or raw category string/symbol ('text', 'app_card',
+      #   'PLAIN_TEXT', ...);
+      # - a Hash of conditions, e.g. {action: 'CREATE_MESSAGE'} or
+      #   {category: 'text'} — all conditions must hold.
+      #
+      # The handler is a Class (instantiated per message) or anything
+      # responding to #call(message). Routes match in registration order;
+      # the first match wins.
+      #
+      # @return [self] (chainable)
+      #
+      def on(matcher, handler = nil, &block)
+        if matcher.is_a?(Hash) && matcher.key?(:handler)
+          raise MixinBot::ArgumentError, 'handler given twice (positional and :handler key)' if handler || block
+
+          handler = matcher[:handler]
+          matcher = matcher.except(:handler)
+        end
+        handler ||= block
+        raise MixinBot::ArgumentError, 'a handler class or callable is required' unless handler
+        unless handler.is_a?(Class) || handler.respond_to?(:call)
+          raise MixinBot::ArgumentError, "handler #{handler.inspect} must be a class or respond to #call"
+        end
+
+        @routes << Route.new(compile_matcher(matcher), handler)
+        self
+      end
+
+      ##
+      # Dispatches one decoded envelope Hash (the reactor's handler contract).
+      # Unmatched envelopes are logged and ignored; handler exceptions are
+      # logged and re-raised so the reactor's ack policy and containment
+      # govern retry/redelivery.
+      #
+      # @param raw [Hash] decoded envelope with 'action' and 'data' keys
+      # @raise [StandardError] when the matched handler raises
+      #
+      def call(raw)
+        message = Message.new(raw, api: @api)
+        route = @routes.find { |candidate| candidate.matches?(message) }
+
+        if route.nil?
+          @logger.call(:unmatched, "action=#{message.action.inspect} category=#{message.category.inspect}")
+          return
+        end
+
+        dispatch(route.handler, message)
+      end
+
+      # Normalizes a category alias or raw category to its canonical form.
+      #
+      # @return [String]
+      # @raise [MixinBot::ArgumentError] for unknown categories
+      #
+      def self.normalize_category(value)
+        key = value.to_s.downcase
+        return CATEGORY_ALIASES[key] if CATEGORY_ALIASES.key?(key)
+
+        upcased = value.to_s.upcase
+        return upcased if upcased.start_with?('PLAIN_', 'SYSTEM_', 'APP_', 'MESSAGE_')
+
+        raise MixinBot::ArgumentError, "unknown message category #{value.inspect}"
+      end
+
+      private
+
+      def dispatch(handler, message)
+        if handler.is_a?(Class)
+          handler.new(message).call
+        elsif handler.respond_to?(:call)
+          handler.call(message)
+        else
+          raise MixinBot::ArgumentError, "handler #{handler.inspect} must be a class or respond to #call"
+        end
+      rescue StandardError => e
+        @logger.call(:handler_error, e)
+        raise
+      end
+
+      def compile_matcher(matcher)
+        case matcher
+        when Hash
+          conditions = matcher.map { |key, value| compile_condition(key, value) }
+          ->(message) { conditions.all? { |condition| condition.call(message) } }
+        when String, Symbol
+          category = self.class.normalize_category(matcher)
+          ->(message) { message.category == category }
+        else
+          raise MixinBot::ArgumentError,
+                "matcher must be a category alias or a conditions Hash, got #{matcher.inspect}"
+        end
+      end
+
+      def compile_condition(key, value)
+        case key.to_sym
+        when :category
+          category = self.class.normalize_category(value)
+          ->(message) { message.category == category }
+        when :action
+          action = value.to_s
+          ->(message) { message.action == action }
+        else
+          raise MixinBot::ArgumentError,
+                "unknown route condition #{key.inspect} (supported: :category, :action)"
+        end
+      end
+    end
+  end
+end

data/lib/mixin_bot/cache_store_adapter.rb

@@ -20,7 +20,9 @@ module MixinBot
     KEY_PREFIX = 'mixin_bot/sessions'
 
     def initialize(cache = nil, expires_in: nil)
-      cache ||= Rails.cache if defined?(Rails)
+      # ::Rails (not bare Rails): lexical lookup under module MixinBot must
+      # never resolve to a MixinBot-namespaced constant.
+      cache ||= ::Rails.cache if defined?(::Rails)
       raise ArgumentError, 'a cache store is required' if cache.nil?
 
       @cache = cache

data/lib/mixin_bot/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'client/error_mapper'
+require_relative 'json_decoder'
 
 module MixinBot
   ##
@@ -24,7 +25,7 @@ module MixinBot
         f.request :retry, max: 2, interval: 0.5, interval_randomness: 0.5, backoff_factor: 2,
                           exceptions: [Faraday::ConnectionFailed, Faraday::TimeoutError]
         f.options.timeout = @config.http_timeout if @config.http_timeout
-        f.response :json
+        f.response :json, parser_options: { decoder: [JSONDecoder, :parse] }
         f.response :logger if @config.debug
       end
     end

data/lib/mixin_bot/computer.rb

@@ -2,6 +2,8 @@
 
 require 'faraday'
 
+require_relative 'json_decoder'
+
 module MixinBot
   # Mixin Computer API client (https://computer.mixin.one).
   class Computer
@@ -15,7 +17,7 @@ module MixinBot
       def connection
         @connection ||= Faraday.new(url: BASE_URI) do |f|
           f.request :json
-          f.response :json
+          f.response :json, parser_options: { decoder: [MixinBot::JSONDecoder, :parse] }
           f.adapter Faraday.default_adapter
         end
       end

data/lib/mixin_bot/json_decoder.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MixinBot
+  # json 3.x made +JSON.parse+ keyword-only, while faraday's JSON middleware
+  # calls its decoder with positional options. Splatted keywords keep this
+  # compatible with both json 2.x and 3.x.
+  module JSONDecoder
+    module_function
+
+    def parse(body, options = {})
+      JSON.parse(body, **options)
+    end
+  end
+end

data/lib/mixin_bot/notifications/mixin_channel.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Loads only when the Noticed gem is already loaded (it is in every app that
+# declares `deliver_by :mixin`); requiring the integration layer without
+# Noticed neither raises nor loads this file's contents.
+return unless defined?(Noticed::Channel)
+
+module MixinBot
+  module Notifications
+    ##
+    # Noticed delivery channel that sends the notification as a Mixin message
+    # over the HTTP message API.
+    #
+    # Notification-class contract (all resolution lives in the notification,
+    # so the channel stays a thin adapter over Noticed's surface):
+    #
+    #   class PaymentReceivedNotification < Noticed::Notification
+    #     deliver_by :mixin                      # or: deliver_by :mixin, bot: :shop
+    #
+    #     def mixin_recipient                    # Mixin user id to deliver to
+    #       recipient.mixin_user_id
+    #     end
+    #
+    #     def mixin_message
+    #       { category: 'PLAIN_TEXT', content: "received #{params[:amount]}" }
+    #     end
+    #   end
+    #
+    # mixin_message supports {category: 'PLAIN_TEXT'|'PLAIN_POST', content:}
+    # and {category: 'APP_CARD', card: {title:, description:, action:, ...}}.
+    # When the notification class does not define #mixin_recipient, the
+    # channel falls back to the recipient record's #mixin_user_id.
+    #
+    # Delivery failures raise out of #deliver — Noticed captures them per
+    # delivery without aborting sibling channels.
+    #
+    class MixinChannel < ::Noticed::Channel
+      def deliver
+        api.send_message(payload)
+      end
+
+      private
+
+      def api
+        @api ||=
+          if params[:bot]
+            MixinBot.bot(params[:bot])
+          else
+            MixinBot.api
+          end
+      end
+
+      def payload
+        message = notification.try(:mixin_message) ||
+                  raise(MixinBot::ArgumentError,
+                        "#{notification.class} must define #mixin_message for the mixin channel")
+
+        options = { recipient_id: recipient_id, data: message[:content] }
+        case message[:category]
+        when 'PLAIN_POST' then api.plain_post(options)
+        when 'APP_CARD' then api.app_card(options.merge(data: message[:card]))
+        else api.plain_text(options)
+        end
+      end
+
+      def recipient_id
+        id =
+          if notification.respond_to?(:mixin_recipient)
+            notification.mixin_recipient
+          elsif recipient.respond_to?(:mixin_user_id)
+            recipient.mixin_user_id
+          end
+
+        raise MixinBot::ArgumentError, 'could not resolve a Mixin recipient id' if id.blank?
+
+        id
+      end
+    end
+  end
+end

data/lib/mixin_bot/outputs/cursor_model.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module MixinBot
+  module Outputs
+    ##
+    # ActiveRecord concern for the generated +MixinPollerCursor+ model
+    # (mixin_bot:outputs generator): one row per bot app id, remembering the
+    # last absorbed output position (the outputs API's own created_at value).
+    #
+    #   class MixinPollerCursor < ApplicationRecord
+    #     include MixinBot::Outputs::CursorModel
+    #   end
+    #
+    # Required columns: bot_app_id (unique), value.
+    #
+    module CursorModel
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def value(bot_app_id:)
+          find_by(bot_app_id:)&.value
+        end
+
+        def advance!(bot_app_id:, value:)
+          record = find_or_initialize_by(bot_app_id:)
+          record.update!(value:)
+        end
+      end
+    end
+  end
+end

data/lib/mixin_bot/outputs/envelope.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module MixinBot
+  module Outputs
+    ##
+    # Application-facing view of one Mixin output (a transfer touching the
+    # bot's Safe UTXO set — inbound or outbound).
+    #
+    # The output stream itself carries amount/asset/state but no memo; the
+    # memo, counterparty, and trace id are bridged lazily — at most once per
+    # output — through the snapshot notification API
+    # (+create_safe_snapshot_notification+). A failed bridge logs a warning
+    # and yields nil fields; processing continues without them.
+    #
+    # Wraps a receipt record (the poller's dedup row): output fields are read
+    # from it and resolved snapshot data is cached back onto it. Receipt-like
+    # objects must expose:
+    #   output_id, amount (String), asset_id, state, transaction_hash,
+    #   output_index, memo, opponent_id, trace_id
+    #   snapshot_bridged?            # bridge already attempted (success or not)
+    #   cache_snapshot!(memo:, opponent_id:, trace_id:)  # write-back
+    #
+    #   envelope.amount        # => BigDecimal
+    #   envelope.memo          # => String or nil (bridged on first access)
+    #   envelope.spent?        # => true when the output is spent
+    #
+    class Envelope
+      attr_reader :receipt, :api
+
+      ##
+      # @param receipt [Object] receipt record backing this envelope
+      # @param api [MixinBot::API] bot client used for the snapshot bridge
+      #
+      def initialize(receipt, api:)
+        @receipt = receipt
+        @api = api
+      end
+
+      def output_id
+        receipt.output_id
+      end
+
+      # The output's amount as a BigDecimal.
+      def amount
+        BigDecimal(receipt.amount.to_s)
+      end
+
+      def asset_id
+        receipt.asset_id
+      end
+
+      def transaction_hash
+        receipt.transaction_hash
+      end
+
+      def output_index
+        receipt.output_index
+      end
+
+      # The output's kernel sequence — unique and monotonic; the key the
+      # outputs API paginates on and the value processors can key on for
+      # ordering.
+      def sequence
+        receipt.sequence
+      end
+
+      # True when the output is spent (outbound from the bot's perspective).
+      def spent?
+        receipt.state == 'spent'
+      end
+
+      def state
+        receipt.state
+      end
+
+      ##
+      # Snapshot-derived memo; nil when the bridge failed or the snapshot has
+      # no memo. Bridged at most once per output.
+      #
+      def memo
+        bridge_snapshot.memo
+      end
+
+      # Snapshot-derived counterparty user id; nil on bridge failure.
+      def opponent_id
+        bridge_snapshot.opponent_id
+      end
+
+      # Snapshot-derived trace id (the sender's idempotency trace); nil on
+      # bridge failure.
+      def trace_id
+        bridge_snapshot.trace_id
+      end
+
+      private
+
+      # Returns the memo/opponent/trace triple after a single bridge attempt.
+      # Receipts whose bridge already ran (success OR failure — the flag is
+      # written in both cases) short-circuit the API call, so each output is
+      # bridged at most once per receipt lifetime, not just per Envelope.
+      def bridge_snapshot
+        return @bridge_snapshot if defined?(@bridge_snapshot)
+
+        if receipt.respond_to?(:snapshot_bridged?) && receipt.snapshot_bridged?
+          return Snapshot.new(memo: receipt.memo, opponent_id: receipt.opponent_id,
+                              trace_id: receipt.trace_id, bridged: true)
+        end
+
+        fetch_snapshot
+      end
+
+      def fetch_snapshot
+        response = api.create_safe_snapshot_notification(
+          transaction_hash: receipt.transaction_hash,
+          output_index: receipt.output_index,
+          receiver_id: api.config.app_id
+        )
+
+        snapshot = response['data'].is_a?(Hash) ? response['data'] : {}
+
+        fields = Snapshot.new(
+          memo: snapshot['memo'],
+          opponent_id: snapshot['opponent_id'],
+          trace_id: snapshot['trace_id'],
+          bridged: true
+        )
+
+        if receipt.respond_to?(:cache_snapshot!)
+          receipt.cache_snapshot!(
+            memo: fields.memo,
+            opponent_id: fields.opponent_id,
+            trace_id: fields.trace_id
+          )
+        end
+
+        fields
+      rescue StandardError => e
+        MixinBot::Outputs.logger.call(:snapshot_bridge_error,
+                                      "#{e.class}: #{e.message} (output #{receipt.output_id})")
+        # Mark the attempt even on failure so later jobs don't re-POST.
+        receipt.cache_snapshot!(memo: nil, opponent_id: nil, trace_id: nil) if receipt.respond_to?(:cache_snapshot!)
+        Snapshot.new(memo: nil, opponent_id: nil, trace_id: nil, bridged: false)
+      end
+
+      # Immutable triple of bridged snapshot fields.
+      Snapshot = Struct.new(:memo, :opponent_id, :trace_id, keyword_init: true) do
+        def initialize(bridged:, memo: nil, opponent_id: nil, trace_id: nil)
+          super(memo:, opponent_id:, trace_id:)
+          @bridged = bridged
+        end
+
+        def bridged?
+          @bridged
+        end
+      end
+    end
+  end
+end