line-message-builder 0.9.0 → 0.10.0

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

@@ -4,18 +4,19 @@ module Line
   module Message
     module Builder
       module Actions
-        # Represents a "postback action" for LINE messages.
+        # 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,
+        # specified +data+ payload. Optionally, +display_text+ 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
+        # == Example
+        #
         #   Line::Message::Builder.with do
         #     text "What do you want to do?"
         #     quick_reply do
@@ -26,39 +27,61 @@ module Line
         #     end
         #   end
         #
-        # @see https://developers.line.biz/en/reference/messaging-api/#postback-action
+        # See also:
+        # - 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.
+          # 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.
+          # :method: label
+          # :call-seq:
+          #   label() -> String or nil
+          #   label(value) -> String or nil
+          #
+          # Sets or gets the 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.
+          # [value]
+          #   The label text for the action
           option :label, default: nil
 
-          # Defines an optional `displayText` for the action.
+          # :method: display_text
+          # :call-seq:
+          #   display_text() -> String or nil
+          #   display_text(value) -> String or nil
+          #
+          # Sets or gets the display text 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.
+          # [value]
+          #   The text to display in the chat (max 300 characters)
           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).
+          # [data]
+          #   The data to be sent in the postback event (required)
+          # [context]
+          #   An optional context object (default: +nil+)
+          # [options]
+          #   Options for the action, including +:label+ and +:display_text+
+          #
+          # Raises RequiredError if +data+ is +nil+ (this check is done in +to_h+
+          # but +data+ is conceptually required on initialization).
+          #
+          # == Example
+          #
+          #   postback = Postback.new(
+          #     "action=buy&item=123",
+          #     context: view_context,
+          #     label: "Buy Now",
+          #     display_text: "I want to buy this item"
+          #   )
           def initialize(data, context: nil, **options, &)
             @data = data
 
@@ -67,9 +90,16 @@ module Line
 
           # 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.
+          # Returns a hash representing the postback action, including +:type+, +:label+
+          # (if set), +:data+, and +:displayText+ (if set).
+          #
+          # Raises RequiredError if +data+ is +nil+.
+          #
+          # == Example
+          #
+          #   postback = Postback.new("action=track", label: "Track Order")
+          #   postback.to_h
+          #   # => { type: "postback", label: "Track Order", data: "action=track" }
           def to_h
             raise RequiredError, "data is required" if data.nil?
 
@@ -80,7 +110,7 @@ module Line
 
           private
 
-          def to_api
+          def to_api # :nodoc:
             {
               type: "postback",
               label: label,
@@ -89,7 +119,7 @@ module Line
             }.compact
           end
 
-          def to_sdkv2
+          def to_sdkv2 # :nodoc:
             {
               type: "postback",
               label: label,

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Line
+  module Message
+    module Builder
+      module Actions
+        # Represents a URI action for LINE messages.
+        #
+        # A URI action opens the given URI when the component it is attached to is
+        # tapped. Unlike Postback, it needs no webhook handling, which makes it the
+        # action to reach for when a component should simply link somewhere.
+        #
+        # The available schemes are +http+, +https+, +line+ and +tel+.
+        #
+        # A separate URI can be opened on desktop by setting +alt_uri_desktop+,
+        # which maps to the <code>altUri.desktop</code> property. When it is set,
+        # LINE for macOS and Windows ignores +uri+. This is supported in Flex
+        # Messages but has no effect in a quick reply.
+        #
+        # == Example: Linking a Flex button to a web page
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Event" do
+        #       bubble do
+        #         footer do
+        #           button style: :primary do
+        #             uri "https://example.com/event", label: "View event"
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # === Example: Opening a different page on desktop
+        #
+        #   uri "https://example.com/mobile",
+        #       label: "Open",
+        #       alt_uri_desktop: "https://example.com/desktop"
+        #
+        # See also:
+        # - https://developers.line.biz/en/reference/messaging-api/#uri-action
+        class Uri < Line::Message::Builder::Base
+          # The URI opened when the action is performed. This is a required
+          # attribute. Max 1000 characters.
+          attr_reader :uri
+
+          # :method: label
+          # :call-seq:
+          #   label() -> String or nil
+          #   label(value) -> String or nil
+          #
+          # Sets or gets the label for the action.
+          #
+          # [value]
+          #   The label text for the action
+          option :label, default: nil
+
+          # :method: alt_uri_desktop
+          # :call-seq:
+          #   alt_uri_desktop() -> String or nil
+          #   alt_uri_desktop(value) -> String or nil
+          #
+          # Sets or gets the URI opened on LINE for macOS and Windows, mapping to
+          # the <code>altUri.desktop</code> property. Has no effect in a quick reply.
+          #
+          # [value]
+          #   The desktop URI (max 1000 characters)
+          option :alt_uri_desktop, default: nil
+
+          # Initializes a new Uri action.
+          #
+          # [uri]
+          #   The URI to open when the action is performed (required)
+          # [context]
+          #   An optional context object (default: +nil+)
+          # [options]
+          #   Options for the action, including +:label+ and +:alt_uri_desktop+
+          # [block]
+          #   An optional block to be instance-eval'd
+          #
+          # == Example
+          #
+          #   Uri.new("https://example.com", label: "Open")
+          def initialize(uri, context: nil, **options, &)
+            @uri = uri
+
+            super(context: context, **options, &)
+          end
+
+          # Converts the Uri action object to a hash suitable for the LINE
+          # Messaging API.
+          #
+          # Raises RequiredError if +uri+ is +nil+.
+          #
+          # == Example
+          #
+          #   Uri.new("https://example.com", label: "Open").to_h
+          #   # => { type: "uri", label: "Open", uri: "https://example.com" }
+          #
+          # [return]
+          #   A hash representing the URI action
+          def to_h
+            raise RequiredError, "uri is required" if uri.nil?
+
+            return to_sdkv2 if context.sdkv2?
+
+            to_api
+          end
+
+          private
+
+          def to_api # :nodoc:
+            {
+              type: "uri",
+              label: label,
+              uri: uri,
+              altUri: alt_uri
+            }.compact
+          end
+
+          def to_sdkv2 # :nodoc:
+            {
+              type: "uri",
+              label: label,
+              uri: uri,
+              alt_uri: alt_uri
+            }.compact
+          end
+
+          def alt_uri # :nodoc:
+            return if alt_uri_desktop.nil?
+
+            { desktop: alt_uri_desktop }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -18,12 +18,15 @@ module Line
       # 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
+      # See also:
+      # - Actions::Message
+      # - Actions::Postback
+      # - Actions::Uri
+      # - https://developers.line.biz/en/reference/messaging-api/#action-objects
       module Actions
         require_relative "actions/message"
         require_relative "actions/postback"
+        require_relative "actions/uri"
       end
     end
   end

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

@@ -3,53 +3,49 @@
 module Line
   module Message
     module Builder
-      # The `Base` class serves as the foundation for all message builder classes
-      # within the `Line::Message::Builder` DSL. It provides core 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`).
+      # message type builders (e.g., Text, Flex::Builder).
       class Base
         class << self
-          # @!visibility private
-          # @!parse extend ClassMethods
-          def inherited(subclass)
+          def inherited(subclass) # :nodoc:
             super
             subclass.extend ClassMethods
           end
         end
 
-        # The `ClassMethods` module is automatically extended by any class that
-        # inherits from {Base}. It provides class-level methods for defining
+        # 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
+          def options # :nodoc:
             @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:
+          # 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`
+          #   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
+          # [name]
+          #   The name of the option to define. This will also be the name of the
+          #   generated instance method.
+          # [default]
+          #   The default value for the option if not explicitly set.
+          # [validator]
+          #   An optional validator object that must respond to +valid!+ method.
+          #   If the value is invalid, the validator should raise an error.
+          #
+          # == Example
+          #
           #   class MyBuilder < Base
           #     option :color, default: "red"
           #     option :size, validator: SizeValidator.new
@@ -74,24 +70,39 @@ module Line
           end
         end
 
+        # The context object used for method delegation.
+        #
+        # When methods are called on the builder that it doesn't respond to,
+        # they are delegated to this context object if it responds to them.
+        # This allows accessing helper methods and variables from the surrounding
+        # environment within the builder DSL.
         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.
+        # [context]
+        #   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.
+        # [options]
+        #   A hash of options to set on the builder instance. These options are
+        #   typically defined using the +option+ method in the builder class.
+        # [block]
+        #   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.
+        #
+        # == Example
+        #
+        #   builder = MyBuilder.new(context: view_context) do
+        #     text "Hello from context"
+        #   end
         def initialize(context: nil, **options, &block)
           @context = context
           @quick_reply = nil
 
+          validate_options!(options)
+
           self.class.options.each do |option|
             send(option, options[option]) if options.key?(option)
           end
@@ -100,15 +111,17 @@ module Line
         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}
+        # 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
+        # :yields: quick_reply
+        #
+        # == Example
+        #
         #   text_message do
         #     text "Please choose an option:"
         #     quick_reply do
@@ -120,34 +133,11 @@ module Line
           @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)
+        def respond_to_missing?(method_name, include_private = false) # :nodoc:
           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, ...)
+        def method_missing(method_name, ...) # :nodoc:
           if context.respond_to?(method_name)
             context.public_send(method_name, ...)
           else
@@ -155,6 +145,20 @@ module Line
           end
         end
 
+        # Converts the builder to a hash representation.
+        #
+        # The format of the hash depends on the mode (API or SDK v2) determined
+        # by the builder's configuration. Subclasses must implement +to_api+ and
+        # +to_sdkv2+ methods to provide the actual conversion logic.
+        #
+        # [return]
+        #   A hash representation of the message in the appropriate format.
+        #
+        # == Example
+        #
+        #   builder = Text.new { text "Hello" }
+        #   builder.to_h
+        #   # => { type: "text", text: "Hello" }
         def to_h
           return to_sdkv2 if sdkv2?
 
@@ -163,11 +167,32 @@ module Line
 
         private
 
-        def to_api
+        # Rejects options the builder does not declare.
+        #
+        # An undeclared option is almost always a typo or a property the LINE API
+        # spells differently. Ignoring it produces a message that is silently
+        # missing the styling that was asked for, which nothing downstream can
+        # detect, so it is refused here instead.
+        #
+        # [options]
+        #   The hash of options passed to the constructor
+        #
+        # Raises ValidationError listing the unknown option and the ones this
+        # builder accepts.
+        def validate_options!(options) # :nodoc:
+          unknown = options.keys - self.class.options
+          return if unknown.empty?
+
+          raise ValidationError,
+                "Unknown option: #{unknown.join(", ")} for #{self.class}. " \
+                "Allowed options are: #{self.class.options.join(", ")}"
+        end
+
+        def to_api # :nodoc:
           raise NotImplementedError, "#{self.class} must implement #to_api"
         end
 
-        def to_sdkv2
+        def to_sdkv2 # :nodoc:
           raise NotImplementedError, "#{self.class} must implement #to_sdkv2"
         end
       end