line-message-builder 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e34932b3afe2a1bbe05967e19991c2d1af583094e2b60be909efa9c773296fe
-  data.tar.gz: 2c7c94550e9b29a943b517aa5b19a9d03ec213a8779df05b1d0c55a886b8872b
+  metadata.gz: c49876bd79a2b1e98639a5e709a41736ebc11e8c7b5bf811ca478c52df762183
+  data.tar.gz: 65ceed1d2fbef231161bc7eb131269354875c39b202da96bb6fcd42edce4bf86
 SHA512:
-  metadata.gz: c60b5ee94ee4e2f8dc658acace8538af12c9ee374f48b5fb5577c4baf43d93d661b2b47e18d8d09ee7f0e99f9fdbd0cdc3ce05e9bfd54c96ad36acd82b7b0cb6
-  data.tar.gz: afb292eec260c30163e79d8108471a7a5db4a722d6f44d54de7e25ae884375968addb2b6be9271240a6aae58023539acaca99109eeba95fc016e0e4aae94f0c8
+  metadata.gz: bf2111f3470856dc021330c2fa73e3275842596d858e636d198f3dd8dcea7bddf9a60a252e4a80eb5e6297126b0ec3afeeaf143181ef565db06af9cf558c93c6
+  data.tar.gz: e98ec6e6696268c00f599de55e6b6acb09067c2370c6fc5357f8d1ee7f74b9b6e7d2c9b59a527ae5bc806ca6c685163311648b3a78641bd028d8ba6b71dc3bf1

data/.document

@@ -0,0 +1,3 @@
+lib
+README.md
+LICENSE.txt

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.7.0"}
+{".":"0.8.0"}

data/.rubocop.yml

@@ -6,6 +6,8 @@ AllCops:
   TargetRubyVersion: 3.1
   NewCops: enable
   SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.8.0](https://github.com/elct9620/line-message-builder/compare/v0.7.0...v0.8.0) (2025-05-24)
+
+
+### Features
+
+* Add GitHub Action for RDoc generation and deployment ([dbb0f79](https://github.com/elct9620/line-message-builder/commit/dbb0f797ae6143bb9f463c8e6c111a5fe1f0a53f))
+* Add GitHub Action for RDoc generation and deployment ([#9](https://github.com/elct9620/line-message-builder/issues/9)) ([c1a9920](https://github.com/elct9620/line-message-builder/commit/c1a99203b3abef99d149ecc7a055367268f5c2f8))
+* add mode option to Line::Message::Builder for SDKv2 support ([f44f787](https://github.com/elct9620/line-message-builder/commit/f44f78758f5cac1dda6cf86f4c1945365c6c1018))
+
+
+### Bug Fixes
+
+* pass context to quick reply actions to resolve sdkv2 method error ([1bec753](https://github.com/elct9620/line-message-builder/commit/1bec7539421c0c11b10d2e906f9ee7f44a1c726f))
+
 ## [0.7.0](https://github.com/elct9620/line-message-builder/compare/v0.6.1...v0.7.0) (2025-05-21)
 
 

data/README.md

@@ -3,6 +3,7 @@
 [![.github/workflows/main.yml](https://github.com/elct9620/line-message-builder/actions/workflows/main.yml/badge.svg)](https://github.com/elct9620/line-message-builder/actions/workflows/main.yml)
 [![codecov](https://codecov.io/gh/elct9620/line-message-builder/graph/badge.svg?token=9TJTSRIL0X)](https://codecov.io/gh/elct9620/line-message-builder)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/elct9620/line-message-builder)
+[![Documentation](https://img.shields.io/badge/docs-gh--pages-brightgreen)](https://elct9620.github.io/line-message-builder/)
 
 Build LINE messages using DSL (Domain Specific Language) in Ruby.
 
@@ -11,6 +12,7 @@ Build LINE messages using DSL (Domain Specific Language) in Ruby.
 - Build LINE messages using DSL
 - Validation of properties
 - RSpec matchers for testing
+- LINE Bot SDK v2 support (WIP)
 
 ## Installation
 
@@ -31,6 +33,12 @@ gem install line-message-builder
 > [!NOTE]
 > Working in progress.
 
+### LLM.txt
+
+The `llm.txt` is available in document assets.
+
+You can get it from [http://aotoki.me/line-message-builder/llm.txt](http://aotoki.me/line-message-builder/llm.txt).
+
 ### Builder
 
 ```ruby

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

@@ -3,22 +3,88 @@
 module Line
   module Message
     module Builder
+      # The `Actions` module serves as a namespace for action objects that can be
+      # associated with various LINE message components, such as buttons in
+      # quick replies or imagemaps. Each class within this module represents a
+      # specific type of action a user can perform.
       module Actions
-        # The Message class is used to build message actions for quick replies.
+        # Represents a "message action" for LINE messages.
+        #
+        # A message action sends a specified text message to the chat from the user
+        # when a button associated with this action is tapped. It's commonly used
+        # in quick replies or other interactive message components.
+        #
+        # @example Creating a message action for a quick reply button
+        #   Line::Message::Builder.with do |root|
+        #     root.text "Select your favorite food:"
+        #     root.quick_reply do |qr|
+        #       # When this button is tapped, the user sends "Pizza"
+        #       qr.button action: :message, label: "Pizza", text: "Pizza"
+        #       # When this button is tapped, the user sends "Sushi"
+        #       qr.button action: :message, label: "Sushi", text: "Sushi"
+        #     end
+        #   end
+        #
+        # @see https://developers.line.biz/en/reference/messaging-api/#message-action
         class Message < Line::Message::Builder::Base
+          # @!attribute [r] text
+          #   @return [String] The text that is sent as a message from the user
+          #     when the action is performed. This is a required attribute.
           attr_reader :text
 
+          # Defines an optional `label` for the action.
+          # The label is recommended by LINE for accessibility purposes, but it's
+          # not displayed in all LINE versions. For some message types like buttons,
+          # the label of the button itself is used as the action's label.
+          #
+          # @!method label(value = nil)
+          #   @param value [String, nil] The label text for the action.
+          #   @return [String, nil] The current label text.
           option :label, default: nil
 
+          # Initializes a new Message action.
+          #
+          # @param text [String] The text to be sent when the action is performed.
+          #   This is a required parameter.
+          # @param context [Object, nil] An optional context object for resolving
+          #   method calls within a block, if one is provided.
+          # @param options [Hash] A hash of options to set instance variables.
+          #   Can include `:label`.
+          # @param block [Proc, nil] An optional block to be instance-eval'd.
+          #   While available, it's not commonly used for simple actions like this.
+          # @raise [RequiredError] if `text` is nil. (This check is done in `to_h`
+          #   but `text` is conceptually required on initialization).
           def initialize(text, context: nil, **options, &)
             @text = text
 
             super(context: context, **options, &)
           end
 
+          # Converts the Message action object to a hash suitable for the LINE
+          # Messaging API.
+          #
+          # @return [Hash] A hash representing the message action.
+          #   Includes `:type`, `:label` (if set), and `:text`.
+          # @raise [RequiredError] if `text` is nil.
           def to_h
             raise RequiredError, "text is required" if text.nil?
 
+            return to_sdkv2 if context.sdkv2?
+
+            to_api
+          end
+
+          private
+
+          def to_api
+            {
+              type: "message",
+              label: label,
+              text: text
+            }.compact
+          end
+
+          def to_sdkv2
             {
               type: "message",
               label: label,

data/lib/line/message/builder/actions/postback.rb

@@ -4,22 +4,83 @@ module Line
   module Message
     module Builder
       module Actions
-        # The Postback class is used to build postback actions for quick replies.
+        # Represents a "postback action" for LINE messages.
+        #
+        # A postback action sends a postback event to your bot's webhook when a
+        # button associated with this action is tapped. The event contains the
+        # specified `data` payload. Optionally, `displayText` can be provided,
+        # which will be shown in the chat as a message from the user.
+        #
+        # This action is useful for triggering specific backend logic or flows
+        # without necessarily displaying a message in the chat, or for displaying
+        # a different message than the data payload.
+        #
+        # @example Creating a postback action for a quick reply button
+        #   Line::Message::Builder.with do |root|
+        #     root.text "What do you want to do?"
+        #     root.quick_reply do |qr|
+        #       qr.button action: :postback,
+        #                 label: "Track Order",
+        #                 data: "action=track_order&order_id=123",
+        #                 display_text: "I want to track my order."
+        #     end
+        #   end
+        #
+        # @see https://developers.line.biz/en/reference/messaging-api/#postback-action
         class Postback < Line::Message::Builder::Base
+          # @!attribute [r] data
+          #   @return [String] The data payload to be sent in the postback event
+          #     to the webhook. This is a required attribute. Max 300 characters.
           attr_reader :data
 
+          # Defines an optional `label` for the action.
+          # The label is recommended by LINE for accessibility. For some message
+          # types (e.g., buttons), the button's label itself is used.
+          #
+          # @!method label(value = nil)
+          #   @param value [String, nil] The label text for the action.
+          #   @return [String, nil] The current label text.
           option :label, default: nil
+
+          # Defines an optional `displayText` for the action.
+          # This is the text that will be displayed in the chat as a message from
+          # the user when the action is performed. If not set, no message is displayed.
+          #
+          # @!method display_text(value = nil)
+          #   @param value [String, nil] The text to display in the chat. Max 300 characters.
+          #   @return [String, nil] The current display text.
           option :display_text, default: nil
 
+          # Initializes a new Postback action.
+          #
+          # @param data [String] The data to be sent in the postback event. This is required.
+          # @param context [Object, nil] An optional context object.
+          # @param options [Hash] Options for the action, including `:label` and `:display_text`.
+          # @param block [Proc, nil] An optional block for instance_eval.
+          # @raise [RequiredError] if `data` is nil. (This check is done in `to_h`
+          #   but `data` is conceptually required on initialization).
           def initialize(data, context: nil, **options, &)
             @data = data
 
             super(context: context, **options, &)
           end
 
+          # Converts the Postback action object to a hash suitable for the LINE Messaging API.
+          #
+          # @return [Hash] A hash representing the postback action.
+          #   Includes `:type`, `:label` (if set), `:data`, and `:displayText` (if set).
+          # @raise [RequiredError] if `data` is nil.
           def to_h
             raise RequiredError, "data is required" if data.nil?
 
+            return to_sdkv2 if context.sdkv2?
+
+            to_api
+          end
+
+          private
+
+          def to_api
             {
               type: "postback",
               label: label,
@@ -27,6 +88,15 @@ module Line
               displayText: display_text
             }.compact
           end
+
+          def to_sdkv2
+            {
+              type: "postback",
+              label: label,
+              data: data,
+              display_text: display_text
+            }.compact
+          end
         end
       end
     end

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

@@ -3,7 +3,24 @@
 module Line
   module Message
     module Builder
-      # The actions module contains classes for building different types of actions
+      # The `Line::Message::Builder::Actions` module serves as a central namespace
+      # for all action objects used within the LINE message builder DSL. Actions
+      # represent operations that can be triggered by users interacting with
+      # message components like buttons (in quick replies, templates, etc.) or
+      # imagemap areas.
+      #
+      # This module itself does not define specific action classes directly but
+      # acts as a container that loads them from individual files (e.g., `message.rb`,
+      # `postback.rb`). Each loaded file defines a class corresponding to a
+      # specific action type supported by the LINE Messaging API.
+      #
+      # By organizing actions under this namespace, the builder provides a clear
+      # and consistent way to create and manage different types of interactive
+      # elements in messages.
+      #
+      # @see Line::Message::Builder::Actions::Message
+      # @see Line::Message::Builder::Actions::Postback
+      # @see https://developers.line.biz/en/reference/messaging-api/#action-objects
       module Actions
         require_relative "actions/message"
         require_relative "actions/postback"

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

@@ -3,21 +3,63 @@
 module Line
   module Message
     module Builder
-      # The base class to provide DSL functionality.
+      # The `Base` class serves as the foundation for all message builder classes
+      # within the `Line::Message::Builder` DSL. It provides core functionality
+      # for defining options, handling initialization, and delegating method calls
+      # to a context object.
+      #
+      # This class is not typically used directly but is inherited by specific
+      # message type builders (e.g., `Text`, `Flex`).
       class Base
         class << self
+          # @!visibility private
+          # @!parse extend ClassMethods
           def inherited(subclass)
             super
             subclass.extend ClassMethods
           end
         end
 
-        # :nodoc:
+        # The `ClassMethods` module is automatically extended by any class that
+        # inherits from {Base}. It provides class-level methods for defining
+        # DSL options and configurations.
         module ClassMethods
+          # Returns an array of option names that have been defined for this class
+          # using the {option} method.
+          #
+          # @return [Array<Symbol>] A list of defined option names.
+          # @!visibility private
           def options
             @options ||= []
           end
 
+          # Defines a new option for the builder class.
+          # This method dynamically creates an instance method on the builder class
+          # with the given `name`. When this instance method is called:
+          # - Without arguments, it returns the current value of the option, or
+          #   the `default` value if not set.
+          # - With an argument, it sets the value of the option. If a `validator`
+          #   is provided, the value is validated before being set.
+          #
+          # @param name [Symbol] The name of the option to define. This will also
+          #   be the name of the generated instance method.
+          # @param default [Object, nil] The default value for the option if not
+          #   explicitly set.
+          # @param validator [#valid!?, nil] An optional validator object that must
+          #   respond to `valid!(value)`. If the value is invalid, the validator
+          #   should raise an error (typically a {ValidationError}).
+          # @return [void]
+          # @example
+          #   class MyBuilder < Base
+          #     option :color, default: "red"
+          #     option :size, validator: SizeValidator.new
+          #   end
+          #
+          #   builder = MyBuilder.new
+          #   puts builder.color # => "red"
+          #   builder.color "blue"
+          #   puts builder.color # => "blue"
+          #   builder.size "large" # Assuming SizeValidator allows "large"
           def option(name, default: nil, validator: nil)
             options << name
 
@@ -34,8 +76,20 @@ module Line
 
         attr_reader :context
 
+        # Initializes a new instance of a builder class.
+        #
+        # @param context [Object, nil] An optional external context object.
+        #   Methods not defined in the builder will be delegated to this context
+        #   if it responds to them. This allows for using helper methods or
+        #   accessing data from the surrounding environment within the builder DSL.
+        # @param options [Hash] A hash of options to set on the builder instance.
+        #   These options are typically defined using the {ClassMethods.option .option}
+        #   method in the builder class.
+        # @param block [Proc, nil] An optional block that is instance-eval'd
+        #   within the new builder instance. This is the primary way the DSL
+        #   is used to define message content.
         def initialize(context: nil, **options, &block)
-          @context = Context.new(context)
+          @context = context
           @quick_reply = nil
 
           self.class.options.each do |option|
@@ -45,14 +99,54 @@ module Line
           instance_eval(&block) if ::Kernel.block_given?
         end
 
+        # Defines a quick reply for the message.
+        # A quick reply consists of a set of buttons that are displayed along
+        # with the message, allowing users to make quick responses.
+        #
+        # The provided block is executed in the context of a new {QuickReply}
+        # instance, where you can define the quick reply buttons.
+        #
+        # @yield [quick_reply] The block is yielded with a {QuickReply} instance.
+        # @return [QuickReply] The created {QuickReply} object.
+        # @example
+        #   text_message do
+        #     text "Please choose an option:"
+        #     quick_reply do
+        #       button action: :message, label: "Option A", text: "You chose A"
+        #       button action: :camera,  label: "Open Camera"
+        #     end
+        #   end
         def quick_reply(&)
           @quick_reply = QuickReply.new(context: context, &)
         end
 
+        # Determines if the builder can respond to a given method, including
+        # checking if the context object can respond to it.
+        # This is part of Ruby's mechanism for `method_missing` and is used
+        # here to enable delegation to the `context` object.
+        #
+        # @param method_name [Symbol] The name of the method.
+        # @param include_private [Boolean] Whether to include private methods
+        #   in the search.
+        # @return [Boolean] `true` if the builder or its context can respond to
+        #   the method, `false` otherwise.
+        # @!visibility private
         def respond_to_missing?(method_name, include_private = false)
           context.respond_to?(method_name, include_private) || super
         end
 
+        # Handles calls to undefined methods by attempting to delegate them to the
+        # `context` object. If the `context` object responds to the method,
+        # it is called. Otherwise, it behaves like the standard `method_missing`.
+        # This allows the DSL to feel more integrated with the surrounding code
+        # by making methods from the `context` directly available within the
+        # builder block.
+        #
+        # @param method_name [Symbol] The name of the missing method.
+        # @param ... [Object] Arguments passed to the method.
+        # @raise [NoMethodError] If neither the builder nor the context can
+        #   handle the method call.
+        # @!visibility private
         def method_missing(method_name, ...)
           if context.respond_to?(method_name)
             context.public_send(method_name, ...)
@@ -60,6 +154,22 @@ module Line
             super
           end
         end
+
+        def to_h
+          return to_sdkv2 if sdkv2?
+
+          to_api
+        end
+
+        private
+
+        def to_api
+          raise NotImplementedError, "#{self.class} must implement #to_api"
+        end
+
+        def to_sdkv2
+          raise NotImplementedError, "#{self.class} must implement #to_sdkv2"
+        end
       end
     end
   end

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

@@ -3,31 +3,151 @@
 module Line
   module Message
     module Builder
-      # The container class is main container to manage messages.
-      class Container < Base
+      # The `Container` class is the top-level entry point for constructing a batch
+      # of LINE messages using the builder DSL. It acts as a holder for one or
+      # more individual message objects (such as {Text} or {Flex} messages).
+      #
+      # When you use `Line::Message::Builder.with {}`, you are operating within
+      # the context of a `Container` instance. This container allows you to define
+      # multiple messages that can be sent together in a single API call to LINE,
+      # although the LINE API typically expects an array of message objects,
+      # which this container helps to build.
+      #
+      # Each message added to the container can also have its own quick reply.
+      #
+      # @example Building multiple messages
+      #   message_payload = Line::Message::Builder.with do |root|
+      #     root.text "Hello, this is the first message!"
+      #     root.flex alt_text: "This is a Flex Message" do |flex_builder|
+      #       flex_builder.bubble do |bubble|
+      #         bubble.body do |body|
+      #           body.text "This is a Flex Message body."
+      #         end
+      #       end
+      #     end
+      #   end.build # => Returns an array of message hashes
+      #
+      # @see Base
+      # @see Text
+      # @see Flex::Builder
+      # @see QuickReply
+      class Container
+        # @!attribute [r] context
+        #   @return [Context] The context object, which can hold external data or
+        #     helper methods accessible within the builder blocks.
         attr_reader :context
 
-        def initialize(context: nil, &)
-          @messages = []
+        # Initializes a new message container.
+        # This is typically not called directly but through `Line::Message::Builder.with`.
+        # The provided block is instance-eval'd, allowing DSL methods like
+        # {#text} and {#flex} to be called directly on the container instance.
+        #
+        # @param context [Object, nil] An optional context object that can be used
+        #   to share data or helper methods within the builder block. It's wrapped
+        #   in a {Context} object.
+        # @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.
+        # @param block [Proc] A block containing DSL calls to define messages
+        #   (e.g., `text "Hello"`, `flex { ... }`).
+        def initialize(context: nil, mode: :api, &block)
+          @messages = [] # Initializes an empty array to store message objects
+          @context = Context.new(context, mode:)
 
-          super
+          instance_eval(&block) if ::Kernel.block_given?
         end
 
+        # Creates a new {Text} message and adds it to this container.
+        #
+        # @param text [String] The text content of the message.
+        # @param options [Hash] Additional options for the text message,
+        #   such as `:quick_reply`. See {Text#initialize}.
+        # @param block [Proc, nil] An optional block that will be instance-eval'd
+        #   in the context of the new {Text} message instance. This can be used
+        #   to add a quick reply to the text message.
+        # @return [Text] The newly created {Text} message object.
+        #
+        # @example
+        #   root.text "Hello, world!" do
+        #     quick_reply do
+        #       button action: :message, label: "Hi!", text: "Hi!"
+        #     end
+        #   end
         def text(text, **options, &)
           @messages << Text.new(text, context: context, **options, &)
         end
 
+        # Creates a new {Flex::Builder} for constructing a Flex Message and adds it
+        # to this container. The block is mandatory and is used to define the
+        # content of the Flex Message using the Flex Message DSL.
+        #
+        # @param options [Hash] Options for the Flex Message, primarily `:alt_text`.
+        #   See {Flex::Builder#initialize}. It's important to provide `alt_text`.
+        # @param block [Proc] A block that will be instance-eval'd in the context
+        #   of the new {Flex::Builder} instance. This block is used to define the
+        #   structure and content of the Flex Message (e.g., bubbles, carousels).
+        # @return [Flex::Builder] The newly created {Flex::Builder} object.
+        # @raise [ArgumentError] if `alt_text` is not provided in options (validation
+        #   is typically within Flex::Builder).
+        #
+        # @example
+        #   root.flex alt_text: "Important information" do |fb|
+        #     fb.bubble do |bubble|
+        #       bubble.header { |h| h.text "Header" }
+        #       bubble.body   { |b| b.text "Body" }
+        #     end
+        #   end
         def flex(**options, &)
           @messages << Flex::Builder.new(context: context, **options, &)
         end
 
+        # Converts all messages held by this container into their hash representations.
+        # This method iterates over each message object (e.g., {Text}, {Flex::Builder})
+        # stored in the container and calls its `to_h` method. The result is an
+        # array of hashes, where each hash represents a single LINE message object
+        # ready for JSON serialization and sending to the LINE Messaging API.
+        #
+        # @return [Array<Hash>] An array of message objects, each represented as a hash.
+        #   This is the format expected by the LINE API for the `messages` field
+        #   in a request body.
         def build
           @messages.map(&:to_h)
         end
 
+        # Converts the array of message hashes (obtained from {#build}) into a
+        # JSON string. This is a convenience method for serializing the messages
+        # payload.
+        #
+        # @param args [Object] Optional arguments that are passed along to `to_json`
+        #   method of the underlying array.
+        # @return [String] A JSON string representing the array of message objects.
         def to_json(*args)
           build.to_json(*args)
         end
+
+        # Checks if a method is defined in the context object.
+        # This is part of Ruby's method_missing mechanism.
+        #
+        # @param method_name [Symbol] The name of the method being checked
+        # @param include_private [Boolean] Whether to include private methods
+        # @return [Boolean] True if the method exists in the context, false otherwise
+        def respond_to_missing?(method_name, include_private = false)
+          context.respond_to?(method_name, include_private) || super
+        end
+
+        # Delegates method calls to the context object if they exist there.
+        # This allows helper methods defined in the context to be called directly
+        # from within the builder DSL.
+        #
+        # @param method_name [Symbol] The name of the method being called
+        # @param args [Array] The arguments passed to the method
+        # @return [Object] The result of calling the method on the context
+        # @raise [NoMethodError] If the method doesn't exist in the context
+        def method_missing(method_name, ...)
+          return context.send(method_name, ...) if context.respond_to?(method_name)
+
+          super
+        end
       end
     end
   end