line-message-builder 0.8.0 → 0.10.0

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

@@ -3,57 +3,69 @@
 module Line
   module Message
     module Builder
-      # The `Actions` module serves as a namespace for action objects that can be
+      # 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
-        # Represents a "message action" for LINE messages.
+        # 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|
+        # == Example
+        #
+        #   Line::Message::Builder.with do
+        #     text "Select your favorite food:"
+        #     quick_reply do
         #       # When this button is tapped, the user sends "Pizza"
-        #       qr.button action: :message, label: "Pizza", text: "Pizza"
+        #       button action: :message, label: "Pizza", text: "Pizza"
         #       # When this button is tapped, the user sends "Sushi"
-        #       qr.button action: :message, label: "Sushi", text: "Sushi"
+        #       button action: :message, label: "Sushi", text: "Sushi"
         #     end
         #   end
         #
-        # @see https://developers.line.biz/en/reference/messaging-api/#message-action
+        # See also:
+        # - 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.
+          # 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.
+          # :method: label
+          # :call-seq:
+          #   label() -> String or nil
+          #   label(value) -> String
+          #
+          # Sets or gets the 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.
+          # [value]
+          #   The label text for the action
           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).
+          # [text]
+          #   The text to be sent when the action is performed (required)
+          # [context]
+          #   An optional context object for resolving method calls within a block
+          # [options]
+          #   A hash of options to set instance variables (can include +:label+)
+          # [block]
+          #   An optional block to be instance-eval'd (not commonly used for simple actions)
+          #
+          # Raises RequiredError if +text+ is nil (this check is done in +to_h+
+          # but text is conceptually required on initialization).
+          #
+          # == Example
+          #
+          #   action = Message.new("Hello, world!")
+          #   action = Message.new("Pizza", label: "Select Pizza")
           def initialize(text, context: nil, **options, &)
             @text = text
 
@@ -63,9 +75,18 @@ module Line
           # 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.
+          # The returned hash includes +:type+, +:label+ (if set), and +:text+.
+          #
+          # Raises RequiredError if +text+ is nil.
+          #
+          # == Example
+          #
+          #   action = Message.new("Pizza")
+          #   action.to_h
+          #   # => { type: "message", text: "Pizza" }
+          #
+          # [return]
+          #   A hash representing the message action
           def to_h
             raise RequiredError, "text is required" if text.nil?
 
@@ -76,7 +97,7 @@ module Line
 
           private
 
-          def to_api
+          def to_api # :nodoc:
             {
               type: "message",
               label: label,
@@ -84,7 +105,7 @@ module Line
             }.compact
           end
 
-          def to_sdkv2
+          def to_sdkv2 # :nodoc:
             {
               type: "message",
               label: label,

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

@@ -4,61 +4,84 @@ 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
-        #   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."
+        # == Example
+        #
+        #   Line::Message::Builder.with do
+        #     text "What do you want to do?"
+        #     quick_reply do
+        #       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
+        # 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