warb 0.1.2 → 1.0.0

data/docs/messages/template.md

@@ -1,327 +0,0 @@
-# Template
-
-Template messages are used to send a message with a specific template.
-
-This is useful for sending messages that have a predefined structure, such as notifications or alerts.
-
-#### Quick Examples
-
-**Note**: For the examples below, take into account `Warb.setup` was called to configure the global client instance.
-
-List available templates:
-```ruby
-Warb.template.list
-```
-
-Sending template messages:
-```ruby
-Warb.template.dispatch(recipient_number, **params)
-```
-
-#### Listing Templates
-
-**Prerequisites**: In order to view templates, you need to have them available in your business account. For more details, refer to the [Meta documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates/template-library). Template creation via API will be covered later in this documentation (coming soon).
-
-You can retrieve all available message templates:
-
-```ruby
-Warb.template.list
-```
-
-##### Optional Parameters
-
-You can optionally filter templates using various parameters:
-
-Limit the number of results:
-```ruby
-Warb.template.list(limit: 10)
-```
-
-Specify which template fields to return:
-```ruby
-Warb.template.list(fields: ["name", "status", "category"])
-```
-
-For a complete list of available fields, refer to the [Meta documentation](https://developers.facebook.com/docs/graph-api/reference/whats-app-business-hsm/#fields).
-
-##### Example Response
-
-```ruby
-{
-  "data" => [
-    {
-      "name" => "hello_world",
-      "status" => "APPROVED",
-      "category" => "UTILITY",
-      "language" => "en_US",
-      "components" => [ ... ],
-      "id" => "1282952826730729"
-    },
-    {
-      "name" => "other_template_001",
-      "status" => "APPROVED",
-      "category" => "MARKETING",
-      "language" => "pt_BR",
-      "components" => [ ... ],
-      "id" => "1948352829250167"
-    }
-  ],
-  "paging" => {
-    "cursors" => {
-      "before" => "...",
-      "after" => "..."
-    }
-  }
-}
-```
-
-#### Sending Template Messages
-
-To send  a template message, you need to provide the template name and the parameters for the template, if any.
-
-```ruby
-Warb.template.dispatch(recipient_number, **params)
-```
-
-Here, `**params` is a named hash parameters that will be passed to the template, as follow:
-| Attribute   | Type              | Required | Description                           |
-|-------------|-------------------|----------|---------------------------------------|
-| `name`      | `String`          | Yes      | The name of the template to use       |
-| `language`  | `String`          | Yes      | The language to use for the template  |
-| `resources` | `Array` or `Hash` | No       | The resources to use for the template |
-
-`name` must be the name of a template that has been created in the WhatsApp Business Platform.
-
-`language` must be a valid language code, such as `en_US` for English (United States) or `fr_FR` for French (France). Also, the specified template must support the specified language.
-
-> You can check `Warb::Language` for a list of supported languages.
-> If yours isn't there, you can refer to this [list with all supported languages](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/supported-languages) by WhatsApp.
-> Just use the value in the `code` column, and it will work.
-
-`resouces` can be an array or a hash of resources that will be used as parameters for the template. At this point, only `text`, `date_time` and `currency` are supported.
-
-If the template uses named parameters, then `resources` must be a hash, as follow:
-```ruby
-customer_name = Warb::Resources::Text.new(content: "Name")
-purchase_date = Warb::Resources::Text.new("January 1, 2023")
-
-Warb.template.dispatch(recipient_number, resources: {
-  customer_name: customer_name,
-  purchase_date: purchase_date
-}, name: "testing", language: "pt_BR")
-```
-
-If the template uses positional parameters, then `resources` must be an array, as follow:
-```ruby
-customer_name = Warb::Resources::Text.new(content: "Name")
-purchase_date = Warb::Resources::DateTime.new("January 1, 2023")
-
-Warb.template.dispatch(recipient_number, resources: [
-  customer_name,
-  purchase_date
-], name: "testing", language: "en_US")
-```
-
-In any case, under the hood, the resources instances' method `build_template_named_parameter` or `build_template_positional_parameter` will be called to build the template parameters accordingly.
-
-Instead of instatiating the resources manually, you can use helper methods as follow:
-```ruby
-Warb.template.dispatch(recipient_number) do |template|
-  template.name = "testing"
-  template.language = Warb::Language::PORTUGUESE_BR
-  template.add_text_parameter(content: "Name")
-  template.add_currency_parameter(code: "USD", amount: 11.42)
-end
-```
-
-Here, `add_text_parameter` and `add_currency_parameter` will build the resources for you with the given named parameters and add them to the template.
-
-Here's a table with all the helper methods you can use to add resources/paramters to the template message:
-| Method Name                     | Resource Type               | Description                                      |
-|---------------------------------|-----------------------------|--------------------------------------------------|
-| `add_text_parameter`            | `Warb::Resources::Text`     | Adds a text parameter to the template            |
-| `add_date_time_parameter`       | `Warb::Resources::DateTime` | Adds a date time parameter to the template       |
-| `add_currency_parameter`        | `Warb::Resources::Currency` | Adds a currency parameter to the template        |
-
-In the example above, notice we only used named parameters (no positional parameters) as arguments to the add parameter methods.
-
-So, the parameters will be built as positional parameters, and the `resources` will be an array.
-
-Also, the resources will be used to substitute the corresponding parameters in your template, in the same order they were added to the parameters/resources list.
-
-If you don't want to worry about the order of the parameters, you may use named parameters.
-
-For that, you have to pass the parameter name (as defined in your template) as the first argument to the helper method, as follow:
-```ruby
-Warb.template.dispatch(recipient_number, name: "testing", language: "pt_BR") do |template|
-  template.add_text_parameter("customer_name", content: "Name")
-  template.add_date_time_parameter("purchase_date", date_time: "January 1, 2023")
-end
-```
-
-This way, the order of the parameters names in the template and the order they were added with the `add_parameter` methods may be entirely different.
-
-One **IMPORTANT** thing to note is that, once defined, the type of the parameters won't be changed.
-
-So, in the following code:
-```ruby
-Warb.template.dispatch(recipient_number, name: "testing", language: "pt_BR") do |template|
-  template.add_date_time_parameter(date_time: "January 1, 2023")
-  template.add_text_parameter("customer_name", content: "Name")
-end
-```
-Your `customer_name` parameter won't behave the way you may expect.
-
-Since the first call to an `add_parameter` method was using the positional parameters syntax, then the internal resources attribute was set to an array, so that means any posterior calls to any `add_parameter` method will simply ignore the named parameter syntax and append the built resource to the list of positional parameters
-
-If the order of the calls was different:
-```ruby
-Warb.template.dispatch(recipient_number, name: "testing", language: "pt_BR") do |template|
-  template.add_text_parameter("customer_name", content: "Name")
-  template.add_date_time_parameter(date_time: "January 1, 2023")
-  template.add_currency_parameter(code: "USD", amount: 10)
-end
-```
-
-1. The first call to `add_parameter` method would set the internal resources/parameter to a hash, with a initial key named `customer_name`, pointing to a text resource
-
-2. Then the `DateTime` resource (built in the second call to `add_parameter` method) would be set as value to the key `""` (empty string) in the named parameter hash.
-
-3. Eventually, the `Currency` resource (in the third call do `add_parameter` method) would be set as value to the same key `""` (empty string) as the previous call, which would overwrite the previous resource.
-
-In this case, the call to the api would result in an error, either due to the mismatch of the count of parameters, or due to not having all named parameters defined.
-
-So, make sure to always use the same parameter syntax accordingly to your template.
-
-The add parameter methods also support block building as well:
-```ruby
-Warb.template.dispatch(recipient_number) do |template|
-  template.name = "testing"
-  template.language = Warb::Language::ENGLISH_US
-
-  template.add_text_parameter(content: "Name")
-
-  template.add_currency_parameter do |currency|
-    currency.code = "USD"
-    currency.amount = 11.42
-    currency.fallback = "$ 11.42"
-  end
-
-  template.add_date_time_parameter do |purchase_date|
-    purchase_date.date_time = "Jan 1st, 2024"
-  end
-end
-```
-
-If your template has any media header, you can set it as follow:
-| Header Type    | Template Instance Method    | Params                                         |
-|----------------|-----------------------------|------------------------------------------------|
-| `image`        | `add_image_header`          | `media_id` or `link`                           |
-| `video`        | `add_video_header`          | `media_id` or `link`                           |
-| `document`     | `add_document_header`       | `media_id` or `link`, `filename`               |
-| `location`     | `add_location_header`       | `latitude`, `longitude`, `name`, and `address` |
-| `text`         | `add_text_header`           | `content`, `parameter_name`                    |
-
-Every time a call is made to any `add_header` method, a new header will be set, overwriting the previous one.
-
-If you just want to change one attribute or another, `add_header` methods return the related resource, so it is possible to set the values if you keep a hold of such instance
-```ruby
-Warb.template.dispatch(recipient_number) do |template|
-  header = template.add_image_header(media_id: "wrong_media_id")
-
-  header.media_id = "correct_media_id"
-end
-```
-
-Also, either only one of `media_id` or `link` must be provided.
-
-The `media_id` must be the id of media uploaded previously to WhatsApp Business Platform, while the `link` must be a public acessible URL.
-
-Check the `upload` section for each media related message, like [`image`](./image.md) or [`document`](./document.md), for more info on how to upload and the supported formats.
-
-For the `document` header, `filename` is important because its extension will determine the preview capability on the recipient's device.
-
-For the `location` header, at least `latitude` and `longitude` must be provided.
-
-`add_header` methods will simply instatiate the corresponding resource class with the given parameters, and then, set it as the header attribute.
-
-For `text` header, note that, due to how the WhatsApp Business Platform works, you can't set the entire content for it (the same that happens with the body of the message).
-
-In this case, `add_text_header`, will simply use whatever was given to it as parameter to build the final header in the WhatsApp Business Platform.
-
-So, for example, if your tamplate header was created with `Hello, {{1}}!`, then the text passed to `add_text_header` will simply be substituted in that `{{1}}`.
-
-If your template was defined using named parameters instead (something like `Hello, {{customer_name}}!`), then you must pass the name of the paramter to `add_text_header` as follow:
-```ruby
-Warb.template.dispatch(recipient_number) do |template|
-  template.add_text_header(content: "John", parameter_name: "customer_name")
-end
-```
-
-When the template instance's `build_payload` method is called (which happens when the message is about to be dispatched), the header param will be created using the `header`'s `build_header` method.
-
-#### Adding Buttons
-
-If your template supports buttons, you can add them using the following methods:
-
-| Button Type        | Template Instance Method      | Params                                    |
-|--------------------|-------------------------------|-------------------------------------------|
-| `quick_reply`      | `add_quick_reply_button`      | `index`                                   |
-| `url`              | `add_dynamic_url_button`      | `index`, `text`                           |
-| `url`              | `add_auth_code_button`        | `index`, `text`                           |
-| `copy_code`        | `add_copy_code_button`        | `index`, `coupon_code`                    |
-| `voice_call`       | `add_voice_call_button`       | `index`                                   |
-| `doesn't apply`    | `add_button`                  | `instance`, `&block`                      |
-
-You can either use the keyword parameters or set the attributes using a block:
-
-```ruby
-Warb.template.dispatch(recipient_number) do |template|
-  template.name = "order_confirmation"
-  template.language = Warb::Language::ENGLISH_US
-
-  # Add a quick reply button
-  template.add_quick_reply_button
-
-  # Add a dynamic URL button
-  template.add_dynamic_url_button do |button|
-    button.text = "dynamic-url-suffix"
-  end
-
-  # Add a copy auth code button
-  template.add_auth_code_button do |button|
-    button.text = "4UTHC0D3"
-  end
-
-  # Add a copy code button
-  template.add_copy_code_button(index: 2) do |button|
-    button.coupon_code = "SAVE20"
-  end
-
-  # Add a voice call button
-  template.add_voice_call_button
-end
-```
-
-or if you'd rather to, you can add buttons using it's component and the `add_button` method:
-
-```ruby
-quick_reply_btn = Warb::Components::QuickReplyButton.new
-
-Warb.template.dispatch(recipient_number) do |template|
-  template.name = "order_confirmation"
-  template.language = Warb::Language::ENGLISH_US
-
-  # Add a quick reply button
-  template.add_button(quick_reply_btn)
-
- # Add a quick reply button, passing a block.
-  template.add_button(quick_reply_btn) { |button| button.index = 1 }
-end
-```
-
-**Note**: The `index` parameter determines the order of the buttons in the template. Make sure the
-indices match the button positions defined in your template. The `index` is automaticaly set if you
-don't do it manually, but it is done based on the number of buttons added with the methods above,
-so if your template has a button that doesn't need configuration like the static url button you'll
-have provide the position of the other buttons.

data/docs/resources/currency.md

@@ -1,22 +0,0 @@
-# Currency
-
-`Warb::Resources::Currency` is a resource, but different from most other resources, it can't be sent. Instead, it's used in a template message as one of its parameters.
-
-Please, refer to  our [templates messaging documentation](../messages/template.md) for more info.
-
-It represents an amount in a specific currency, which can be set with the following attributes:
-| Attribute  | Type               | Required | Description                                                 |
-|------------|--------------------|----------|-------------------------------------------------------------|
-| `amount`   | `Integer`, `Float` | Yes      | The amount to be represented in the given currency          |
-| `code`     | `String`           | Yes      | The code of the currency to be used                         |
-| `fallback` | `String`           | No       | A fallback value to be used in case the code can't be found |
-
-Since it is used in template messages, it implements both `build_template_named_parameter` and `build_template_positional_parameter`, which prepares the resource for using as parameter.
-
-If no `fallback` value is given, then a default one, based on the given `amount` and `currency` is used.
-
-In the WhatsApp Business Platform, the `code` will be used to represent the given `amount` according to the specific currency.
-
-But if the given code doesn't exist, or is not supported, then the given `fallback` value will be used instead.
-
-For the `code`, you must use one currency code like `USD` or `BRL`. `Warb::Resources::Currency` offers some of the most used currencies. You can also [check here](https://www.iso.org/iso-4217-currency-codes.html) for more detailed info and other available options.

data/docs/resources/date_time.md

@@ -1,11 +0,0 @@
-# Date Time
-
-`Warb::Resources::DateTime` is a resource, but different from most other resources, it can't be sent. Instead, it's used in a template message as one of its parameters.
-
-Please, refer to  our [templates messaging documentation](../messages/template.md) for more info.
-
-It simply represents a date time object, with the unique param/attribute being `date_time`.
-
-Although its name is `date_time`, its content can be any string, like `"January 1st"`, `"2020-01-01"` or `"Wednesday, Jan, 1st, 2020"`.
-
-Since it is used in template messages, it implements both `build_template_named_parameter` and `build_template_positional_parameter`, which prepares the resource for using as parameter.

data/docs/resources/index.md

@@ -1,14 +0,0 @@
-# Resources
-
-Most of the resources can be sent as message. Check the [messages](../messages/index.md) for detailed info.
-
-But there are some resources which act more like a component, not being used alone by themself.
-
-There are also, resources which can be used alone, and as components for other messages types, like the `Text` resource.
-
-Such resources, and where they are used, are listed bellow:
-| Resource                    | Documentation                | Used at                                                                              |
-|-----------------------------|------------------------------|--------------------------------------------------------------------------------------|
-| `Warb::Resources::Currency` | [Currency](./currency.md)    | [Template Messaging](../messages/template.md)                                        |
-| `Warb::Resources::DateTime` | [Date Time](./date_time.md)  | [Template Messaging](../messages/template.md)                                        |
-| `Warb::Resources::Text`     | [Text](./text.md)            | [Text Messaging](../messages/text.md), [Template Messaging](../messages/template.md) |

data/docs/resources/text.md

@@ -1,9 +0,0 @@
-# Text
-
-`Warb::Resources::Text` is a resource, which represents a text.
-
-It can be used as a [simple message](../messages/text.md), as a text header for some interactive messages, like the [reply button message](../messages/interactive_reply_button.md) and as [parameters for templates](../messages/template.md) variables.
-
-In the [text messaging documentation](../messages/text.md) there is a table with the corresponding attributes.
-
-Aside from such attributes, `Text` resource also provides the `build_template_named_parameter` and `build_template_positional_parameter` methods, which are using under the hood for the template messaging feature.

data/lib/warb/components/button.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module Warb
-  module Components
-    class Button < Component
-      attr_accessor :index, :sub_type
-
-      def initialize(**params)
-        params[:sub_type] = button_type unless params[:sub_type]
-
-        super
-      end
-
-      def to_h
-        {
-          type: 'button',
-          sub_type: sub_type || @params[:sub_type],
-          index: index || @params[:index]
-        }
-      end
-
-      private
-
-      def button_type
-        raise NotImplementedError
-      end
-    end
-  end
-end

data/lib/warb/components/component.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Warb
-  module Components
-    class Component
-      def initialize(**params)
-        @params = params
-      end
-
-      def to_h
-        raise NotImplementedError
-      end
-
-      protected
-
-      attr_reader :params
-    end
-  end
-end

data/lib/warb/components/copy_code_button.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module Warb
-  module Components
-    class CopyCodeButton < Button
-      BUTTON_TYPE = 'copy_code'
-
-      attr_accessor :coupon_code
-
-      def to_h
-        button_payload = super
-
-        if coupon_code || @params[:coupon_code]
-          button_payload[:parameters] = Array.new(1, {
-                                                    type: 'coupon_code',
-                                                    coupon_code: coupon_code || @params[:coupon_code]
-                                                  })
-        end
-
-        button_payload
-      end
-
-      private
-
-      def button_type
-        BUTTON_TYPE
-      end
-    end
-  end
-end

data/lib/warb/components/quick_reply_button.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Warb
-  module Components
-    class QuickReplyButton < Button
-      BUTTON_TYPE = 'quick_reply'
-
-      private
-
-      def button_type
-        BUTTON_TYPE
-      end
-    end
-  end
-end

data/lib/warb/components/url_button.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module Warb
-  module Components
-    class UrlButton < Button
-      BUTTON_TYPE = 'url'
-
-      attr_accessor :text
-
-      def to_h
-        button_payload = super
-
-        if text || @params[:text]
-          button_payload[:parameters] = Array.new(1, {
-                                                    type: 'text',
-                                                    text: text || @params[:text]
-                                                  })
-        end
-
-        button_payload
-      end
-
-      private
-
-      def button_type
-        BUTTON_TYPE
-      end
-    end
-  end
-end

data/lib/warb/components/voice_call_button.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Warb
-  module Components
-    class VoiceCallButton < Button
-      BUTTON_TYPE = 'voice_call'
-
-      private
-
-      def button_type
-        BUTTON_TYPE
-      end
-    end
-  end
-end

data/lib/warb/errors.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-
-module Warb
-  class RequestError < StandardError; end
-  class BadRequest < RequestError; end
-  class Unauthorized < RequestError; end
-  class Forbidden < RequestError; end
-  class NotFound < RequestError; end
-  class InternalServerError < RequestError; end
-  class ServiceUnavailable < RequestError; end
-
-  # custom error classes
-  class IntegrityError < Forbidden; end
-  class InvalidBusinessNumber < BadRequest; end
-
-  class CustomErrors
-    def build
-      {
-        400 => {
-          33 => InvalidBusinessNumber
-        }
-      }
-    end
-  end
-end

data/lib/warb/language.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module Warb
-  module Language
-    ENGLISH_US = 'en_US'
-    PORTUGUESE_BR = 'pt_BR'
-  end
-end

data/lib/warb/resources/currency.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Warb
-  module Resources
-    class Currency < Resource
-      BRL = 'BRL'
-      USD = 'USD'
-
-      attr_accessor :amount, :code, :fallback
-
-      def initialize(**params)
-        super
-
-        @code = params[:code]
-        @amount = params[:amount]
-        @fallback = params[:fallback]
-      end
-
-      def build_template_named_parameter(parameter_name)
-        common_currency_params.merge(parameter_name: parameter_name)
-      end
-
-      def build_template_positional_parameter
-        common_currency_params
-      end
-
-      private
-
-      # rubocop:disable Naming/VariableNumber
-      def common_currency_params
-        {
-          type: 'currency',
-          currency: {
-            amount_1000: amount * 1000,
-            code: code,
-            fallback_value: fallback || default_fallback_value
-          }
-        }
-      end
-      # rubocop:enable Naming/VariableNumber
-
-      def default_fallback_value
-        "#{amount} (#{code})"
-      end
-    end
-  end
-end

data/lib/warb/resources/date_time.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Warb
-  module Resources
-    class DateTime < Resource
-      attr_accessor :date_time
-
-      def initialize(date_time = nil, **params)
-        super(**params)
-
-        @date_time = date_time || params[:date_time]
-      end
-
-      def build_template_named_parameter(parameter_name)
-        common_date_time_params.merge(parameter_name: parameter_name)
-      end
-
-      def build_template_positional_parameter
-        common_date_time_params
-      end
-
-      private
-
-      def common_date_time_params
-        {
-          type: 'date_time',
-          date_time: {
-            fallback_value: date_time
-          }
-        }
-      end
-    end
-  end
-end