line-message-builder 0.9.0 → 0.10.0

data/lib/line/message/builder/quick_reply.rb

@@ -3,14 +3,109 @@
 module Line
   module Message
     module Builder
-      # The QuickReply allows to attach quick reply buttons to a message.
+      # The QuickReply class provides a builder for creating quick reply buttons
+      # that can be attached to text messages or flex messages in the LINE Messaging API.
+      #
+      # Quick reply buttons appear at the bottom of the chat screen and allow users
+      # to quickly respond to messages with predefined actions. They provide a
+      # convenient way to guide user interactions without requiring typing.
+      #
+      # Quick replies support:
+      # - Message actions that send text messages when tapped
+      # - Postback actions that send data to your webhook
+      # - Optional image icons for each button (up to 13 buttons total)
+      #
+      # == Example: Basic quick reply with message actions
+      #
+      #   Line::Message::Builder.with do
+      #     text "Choose your favorite:" do
+      #       quick_reply do
+      #         message "Pizza", label: "Pizza"
+      #         message "Sushi", label: "Sushi"
+      #       end
+      #     end
+      #   end
+      #
+      # == Example: Quick reply with postback actions
+      #
+      #   Line::Message::Builder.with do
+      #     text "What would you like to do?" do
+      #       quick_reply do
+      #         postback "action=order", label: "Place Order", display_text: "I want to order"
+      #         postback "action=track", label: "Track Order"
+      #       end
+      #     end
+      #   end
+      #
+      # == Example: Quick reply with image icons
+      #
+      #   Line::Message::Builder.with do
+      #     text "Select a category:" do
+      #       quick_reply do
+      #         message "Food", label: "Food", image_url: "https://example.com/food.png"
+      #         message "Drinks", label: "Drinks", image_url: "https://example.com/drinks.png"
+      #       end
+      #     end
+      #   end
+      #
+      # See also:
+      # - Text
+      # - Actions::Message
+      # - Actions::Postback
+      # - https://developers.line.biz/en/docs/messaging-api/using-quick-reply/
       class QuickReply < Line::Message::Builder::Base
+        # Creates a new quick reply builder.
+        #
+        # Quick reply builders manage a collection of action buttons that appear
+        # at the bottom of messages. The builder provides methods to add message
+        # and postback actions with optional image icons.
+        #
+        # [context]
+        #   An optional context object for method delegation (default: +nil+)
+        # [block]
+        #   Block for configuring quick reply buttons using +message+, +postback+
+        #   and +uri+ methods
+        #
+        # == Example
+        #
+        #   quick_reply = QuickReply.new(context: view_context) do
+        #     message "Yes", label: "Yes"
+        #     message "No", label: "No"
+        #   end
         def initialize(context: nil, &)
           @items = []
 
           super
         end
 
+        # Adds a message action button to the quick reply.
+        #
+        # Message actions send the specified text as a message from the user when
+        # the button is tapped. This is useful for providing predefined response
+        # options that simplify user interaction.
+        #
+        # [text]
+        #   The text message to send when the button is tapped
+        # [label]
+        #   The label text displayed on the button (required)
+        # [image_url]
+        #   Optional icon image URL for the button (default: +nil+)
+        # [block]
+        #   Optional block for additional configuration
+        #
+        # == Example: Basic message button
+        #
+        #   quick_reply do
+        #     message "I agree", label: "Yes"
+        #     message "I disagree", label: "No"
+        #   end
+        #
+        # == Example: Message button with icon
+        #
+        #   quick_reply do
+        #     message "Order pizza", label: "Pizza",
+        #             image_url: "https://example.com/pizza.png"
+        #   end
         def message(text, label:, image_url: nil, &)
           action(
             Actions::Message.new(text, context: context, label: label, &),
@@ -18,6 +113,46 @@ module Line
           )
         end
 
+        # Adds a postback action button to the quick reply.
+        #
+        # Postback actions send data to your bot's webhook when the button is tapped,
+        # allowing you to trigger backend logic without displaying a message. Optionally,
+        # you can specify display text that will appear in the chat as if the user
+        # sent it.
+        #
+        # [data]
+        #   The data payload to send to the webhook (max 300 characters)
+        # [label]
+        #   The label text displayed on the button (default: +nil+)
+        # [display_text]
+        #   Text to display in chat when tapped (default: +nil+)
+        # [image_url]
+        #   Optional icon image URL for the button (default: +nil+)
+        # [block]
+        #   Optional block for additional configuration
+        #
+        # == Example: Basic postback button
+        #
+        #   quick_reply do
+        #     postback "action=yes", label: "Yes"
+        #     postback "action=no", label: "No"
+        #   end
+        #
+        # == Example: Postback with display text
+        #
+        #   quick_reply do
+        #     postback "action=order&item=pizza",
+        #              label: "Order Pizza",
+        #              display_text: "I'd like to order a pizza"
+        #   end
+        #
+        # == Example: Postback button with icon
+        #
+        #   quick_reply do
+        #     postback "action=confirm",
+        #              label: "Confirm",
+        #              image_url: "https://example.com/check.png"
+        #   end
         def postback(data, label: nil, display_text: nil, image_url: nil, &)
           action(
             Actions::Postback.new(data, context: context, label: label, display_text: display_text, &),
@@ -25,9 +160,44 @@ module Line
           )
         end
 
+        # Adds a URI action button to the quick reply.
+        #
+        # URI actions open the given URI when the button is tapped, without any
+        # webhook handling. The <code>altUri.desktop</code> property is not
+        # supported in a quick reply, so Actions::Uri#alt_uri_desktop has no
+        # effect here.
+        #
+        # [uri]
+        #   The URI to open. Schemes +http+, +https+, +line+ and +tel+
+        # [label]
+        #   The label text displayed on the button (required)
+        # [image_url]
+        #   Optional icon image URL for the button (default: +nil+)
+        # [block]
+        #   Optional block for additional configuration
+        #
+        # == Example: Basic URI button
+        #
+        #   quick_reply do
+        #     uri "https://example.com/menu", label: "See menu"
+        #   end
+        #
+        # == Example: URI button with icon
+        #
+        #   quick_reply do
+        #     uri "tel:+81312345678", label: "Call us",
+        #         image_url: "https://example.com/phone.png"
+        #   end
+        def uri(uri, label:, image_url: nil, &)
+          action(
+            Actions::Uri.new(uri, context: context, label: label, &),
+            image_url
+          )
+        end
+
         private
 
-        def to_api
+        def to_api # :nodoc:
           {
             items: @items.map do |item, image_url|
               {
@@ -39,7 +209,7 @@ module Line
           }
         end
 
-        def to_sdkv2
+        def to_sdkv2 # :nodoc:
           {
             items: @items.map do |item, image_url|
               {
@@ -51,7 +221,7 @@ module Line
           }
         end
 
-        def action(action, image_url)
+        def action(action, image_url) # :nodoc:
           @items << [action, image_url]
         end
       end

data/lib/line/message/builder/text.rb

@@ -3,10 +3,77 @@
 module Line
   module Message
     module Builder
-      # Text message builder.
+      # The Text class provides a builder for creating simple text messages
+      # in the LINE Messaging API. Text messages are the most basic message type,
+      # consisting of plain text content with optional quick reply buttons and
+      # quote tokens for replying to specific messages.
+      #
+      # Text messages support:
+      # - Plain text content (up to 5,000 characters)
+      # - Quick reply buttons for user interaction
+      # - Quote tokens to reply to specific messages in a conversation
+      #
+      # == Example: Basic text message
+      #
+      #   Line::Message::Builder.with do
+      #     text "Hello, world!"
+      #   end
+      #
+      # == Example: Text with quick reply
+      #
+      #   Line::Message::Builder.with do
+      #     text "Choose an option:" do
+      #       quick_reply do
+      #         button action: :message, label: "Yes", text: "I agree"
+      #         button action: :message, label: "No", text: "I disagree"
+      #       end
+      #     end
+      #   end
+      #
+      # == Example: Text with quote token
+      #
+      #   Line::Message::Builder.with do
+      #     text "This is a reply" do
+      #       quote_token "sample_quote_token_value"
+      #     end
+      #   end
+      #
+      # The Text builder inherits from Base and can be used within the
+      # Line::Message::Builder.with block using the +text+ method.
       class Text < Base
+        # :method: quote_token
+        # :call-seq:
+        #   quote_token() -> String or nil
+        #   quote_token(value) -> String
+        #
+        # Sets or gets the quote token for replying to a specific message.
+        #
+        # Quote tokens allow your bot to quote and reply to a specific message
+        # in the conversation. When set, the original message being replied to
+        # will be displayed above the new message.
+        #
+        # [value]
+        #   The quote token string obtained from a webhook event
         option :quote_token, default: nil
 
+        # Creates a new text message builder.
+        #
+        # [text]
+        #   The text content of the message (up to 5,000 characters)
+        # [context]
+        #   An optional context object for method delegation (default: +nil+)
+        # [option]
+        #   Additional options to configure the text message
+        # [block]
+        #   Optional block for configuring quick replies or quote token
+        #
+        # == Example
+        #
+        #   text = Text.new("Hello!", context: view_context) do
+        #     quick_reply do
+        #       button action: :message, label: "Hi", text: "Hi back!"
+        #     end
+        #   end
         def initialize(text, context: nil, **options, &block)
           @text = text
 
@@ -15,7 +82,7 @@ module Line
 
         private
 
-        def to_api
+        def to_api # :nodoc:
           {
             type: "text",
             text: @text,
@@ -24,7 +91,7 @@ module Line
           }.compact
         end
 
-        def to_sdkv2
+        def to_sdkv2 # :nodoc:
           {
             type: "text",
             text: @text,

data/lib/line/message/builder/version.rb

@@ -3,7 +3,7 @@
 module Line
   module Message
     module Builder
-      VERSION = "0.9.0"
+      VERSION = "0.10.0"
     end
   end
 end

data/lib/line/message/builder.rb

@@ -35,19 +35,22 @@ module Line
       module_function
 
       # Entry point for building a message container.
-      # This method initializes a new message {Container} and evaluates the
+      # This method initializes a new message Container and evaluates the
       # provided block within the context of that container.
       #
-      # @param context [Object, nil] An optional context object that can be made
-      #   available within the builder block. This can be useful for accessing
-      #   helper methods or data within the block.
-      # @param mode [Symbol] The mode to use for building messages. Can be either
-      #   `:api` (default) for direct LINE Messaging API format or `:sdkv2` for
-      #   LINE Bot SDK v2 compatible format.
-      # @yield [container] The block is yielded with the newly created {Container}
-      #   instance, allowing you to define the message structure using the DSL.
-      # @return [Container] The initialized message container with the defined structure.
-      # @example
+      # [context]
+      #   An optional context object that can be made available within the builder
+      #   block. This can be useful for accessing helper methods or data within the
+      #   block.
+      # [mode]
+      #   The mode to use for building messages. Can be either <code>:api</code> (default) for
+      #   direct LINE Messaging API format or <code>:sdkv2</code> for LINE Bot SDK v2 compatible
+      #   format.
+      #
+      # :yields: container
+      #
+      # == Example
+      #
       #   message = Line::Message::Builder.with do
       #     text "Hello, world!"
       #   end

data/lib/line/message/rspec/matchers/have_flex_bubble.rb

@@ -51,7 +51,7 @@ module Line
           end
         end
 
-        def have_line_flex_bubble(expected = nil) # rubocop:disable Naming/PredicateName
+        def have_line_flex_bubble(expected = nil) # rubocop:disable Naming/PredicatePrefix
           HaveFlexBubble.new(expected)
         end
       end

data/lib/line/message/rspec/matchers/have_flex_component.rb

@@ -69,11 +69,11 @@ module Line
           end
         end
 
-        def have_line_flex_component(&) # rubocop:disable Naming/PredicateName
+        def have_line_flex_component(&) # rubocop:disable Naming/PredicatePrefix
           HaveFlexComponent.new(&)
         end
 
-        def have_line_flex_box(**options) # rubocop:disable Naming/PredicateName
+        def have_line_flex_box(**options) # rubocop:disable Naming/PredicatePrefix
           options = Utils.stringify_keys!(options, deep: true)
 
           HaveFlexComponent.new(expected_desc: "box(#{options.inspect})") do |content|
@@ -83,7 +83,7 @@ module Line
           end
         end
 
-        def have_line_flex_text(text, **options) # rubocop:disable Naming/PredicateName
+        def have_line_flex_text(text, **options) # rubocop:disable Naming/PredicatePrefix
           options = Utils.stringify_keys!(options, deep: true)
 
           HaveFlexComponent.new(expected_desc: "text(#{text.inspect})") do |content|
@@ -93,7 +93,7 @@ module Line
           end
         end
 
-        def have_line_flex_button(type, **options) # rubocop:disable Naming/PredicateName
+        def have_line_flex_button(type, **options) # rubocop:disable Naming/PredicatePrefix
           options = Utils.stringify_keys!(options, deep: true)
 
           HaveFlexComponent.new(expected_desc: "#{type} button(#{options.inspect})") do |content|
@@ -106,7 +106,7 @@ module Line
           end
         end
 
-        def have_line_flex_image(url, **options) # rubocop:disable Naming/PredicateName
+        def have_line_flex_image(url, **options) # rubocop:disable Naming/PredicatePrefix
           options = Utils.stringify_keys!(options, deep: true)
 
           HaveFlexComponent.new(expected_desc: "image(#{url.inspect})") do |content|
@@ -116,7 +116,17 @@ module Line
           end
         end
 
-        def have_line_flex_span(text, **options) # rubocop:disable Naming/PredicateName
+        def have_line_flex_icon(url, **options) # rubocop:disable Naming/PredicatePrefix
+          options = Utils.stringify_keys!(options, deep: true)
+
+          HaveFlexComponent.new(expected_desc: "icon(#{url.inspect})") do |content|
+            next false unless content["type"] == "icon"
+
+            ::RSpec::Matchers::BuiltIn::Include.new({ "url" => url, **options }).matches?(content)
+          end
+        end
+
+        def have_line_flex_span(text, **options) # rubocop:disable Naming/PredicatePrefix
           options = Utils.stringify_keys!(options, deep: true)
 
           HaveFlexComponent.new(expected_desc: "span(#{text.inspect})") do |content|

data/lib/line/message/rspec/matchers/have_flex_message.rb

@@ -37,7 +37,7 @@ module Line
           end
         end
 
-        def have_line_flex_message(expected = nil) # rubocop:disable Naming/PredicateName
+        def have_line_flex_message(expected = nil) # rubocop:disable Naming/PredicatePrefix
           HaveFlexMessage.new(expected)
         end
       end

data/lib/line/message/rspec/matchers/have_flex_separator.rb

@@ -5,7 +5,7 @@ module Line
     module RSpec
       # :nodoc:
       module Matchers
-        def have_line_flex_separator(**options) # rubocop:disable Naming/PredicateName
+        def have_line_flex_separator(**options) # rubocop:disable Naming/PredicatePrefix
           options = Utils.stringify_keys!(options, deep: true)
 
           HaveFlexComponent.new(expected_desc: "separator(#{options.inspect})") do |content|

data/lib/line/message/rspec/matchers/have_quick_reply.rb

@@ -44,7 +44,7 @@ module Line
           end
         end
 
-        def have_line_quick_reply(expected = nil) # rubocop:disable Naming/PredicateName
+        def have_line_quick_reply(expected = nil) # rubocop:disable Naming/PredicatePrefix
           HaveQuickReply.new(expected)
         end
       end

data/lib/line/message/rspec/matchers/have_text_message.rb

@@ -38,7 +38,7 @@ module Line
           end
         end
 
-        def have_line_text_message(*expected) # rubocop:disable Naming/PredicateName
+        def have_line_text_message(*expected) # rubocop:disable Naming/PredicatePrefix
           HaveTextMessage.new(expected)
         end
       end