warb 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 58ff4cfa4904a9a820c4b5906b947b6f5dcbd3e5a3afa76a9e88ed3f83488bb8
+  data.tar.gz: 1edcbcef65fd5f128cb0cf475f4b5c6ae8e4e285a4b57335b80818e0487f874a
+SHA512:
+  metadata.gz: 43cabbb2bcd395dbbc32eacf0f170e00c5fa913f9edbe4543b9b19f81278648ccae955ac64601182fc468ab02ae81cdb81ae1c07d4601f793dd1645cad28a698
+  data.tar.gz: f7ef031988f7c39be607047ebab9e56d627b848527fce0baa5043f1108a93e378e4e7b6d7df853240bcdba9ccb46b0c0c8ba135833fc31fbccaf01175dab9ba6

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.0.0] - 2025-07-01
+
+### Added
+- Messages sending
+  - Text
+  - Audio
+  - Image
+  - Video
+  - Document
+  - Sticker
+  - Contact
+  - Location
+  - Location Request
+  - Interactive List
+  - Interactive Reply Button
+  - Interactive Call to Action URL
+  - Draft Flows
+- Message builder module using blocks
+- Media Uploading/Downloading
+- Message Reaction
+- Typing/Mark Messages as read indicators

data/README.md

@@ -0,0 +1,120 @@
+# Warb
+
+<p>
+  <img src="https://img.shields.io/badge/em_desenvolvimento-lightgreen?label=status"/>
+  <img src="https://img.shields.io/badge/0.0.0-lightgreen?label=version"/>
+</p>
+
+A Ruby Gem focused on wrap all the functionalities and use cases of the WhatsApp Business API. With Warb you can send messages, audio, images, videos, locations and so much more.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## Configuration
+
+If you don't have a **facebook developer account**, **business portfolio** and **meta app** created yet, please redirect to this [official documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) to get started.
+
+### Rails
+
+To use Warb in your Rails application first you will need to initialize it in `config/initializers/warb.rb`:
+
+```ruby
+Warb.setup do |config|
+  config.access_token = <YOUR_WHATSAPP_BUSINESS_ACCESS_TOKEN>
+  config.business_id = <YOUR_WHATSAPP_BUSINESS_ID>
+  config.sender_id = <YOUR_WHATSAPP_BUSINESS_PHONE_ID>
+  config.adapter = <YOUR_ADAPTER_CHOICE> # defaults to Faraday.default_adapter (which is "":net_http" at the moment)
+  config.logger = <YOUR_PERSONALIZED_LOGGER> # defaults to Logger.new($stdout)
+end
+```
+
+If you would like a more direct way to use it, you can always instanciate it directly:
+
+```ruby
+warb = Warb.new(
+  access_token: <YOUR_WHATSAPP_BUSINESS_ACCESS_TOKEN>,
+  business_id: <YOUR_WHATSAPP_BUSINESS_ID>,
+  sender_id: <YOUR_WHATSAPP_BUSINESS_PHONE_ID>
+  adapter: <YOUR_ADAPTER_CHOICE> # defaults to Faraday.default_adapter (which is "":net_http" at the moment)
+  logger: <YOUR_PERSONALIZED_LOGGER> # defaults to Logger.new($stdout)
+)
+```
+
+## Usage
+
+### Initial Steps
+
+Warb is simple to use — either directly from the module or via an instance.
+
+The **first** and **second** usage modes share a common global configuration instance. The **third** mode, however, creates a new configuration instance, allowing you to define separate local configurations **based on the global configuration (if it exists)** when needed.
+
+1. From the Warb module:
+```ruby
+Warb.message.dispatch(recipient_number, message: "Hello from warb!")
+```
+
+2. From the Warb instance returned from `.setup`:
+```ruby
+warb = Warb.setup { |config| ... }
+
+warb.message.dispatch(recipient_number, message: "Hello from warb!")
+```
+
+3. From the Warb instance return from `.new`:
+```ruby
+warb = Warb.new(...)
+
+warb.message.dispatch(recipient_number, message: "Hello from warb!")
+```
+
+### What more can we do?
+
+You can also pass a block to the `dispatch` method, which look like this:
+
+```ruby
+Warb.message.dispatch(recipient_number) do |builder|
+  builder.message = "Hello from warb!"
+end
+```
+
+### Find all usage examples
+
+We suggest heading to the `examples/` directory, where you'll find documentation files with plenty of usage examples, organized by **Resources** (**Resources** are the types of messages you can send via WhatsApp using Warb).
+
+You can also check the [`docs`](docs/README.md) for a more structured overview of the available resources and their usage.
+
+### Webhook Support
+
+You might want to take action in response to messages users send. For example:
+
+1. A user sends a message like: “generate an image based on...”
+2. You receive the message, so you mark it as read to let the user know their request was acknowledged.
+3. Since the operation might take some time, you send a typing indicator to show that the request is being processed.
+
+To enable this kind of flow, you’ll need to know **when** a message is received. For that, you’ll need to run your own server to listen for incoming webhook events and respond accordingly.
+
+> ⚠️ **Note:** This gem **does not** provide built-in support for webhooks.
+> However, you can look at [`examples/webhook.rb`](examples/webhook.rb) for a starting point on how to implement it. Also, check the [official documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/payload-examples) for more details if you get stuck.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/warb.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/README.md

@@ -0,0 +1,13 @@
+# Warb Documentation
+
+## Configuration
+Refer to [setup](setup.md) for more details on how to configure Warb.
+
+## Webhook
+Refer to [webhook](webhook.md) for more details on how to setup a webhook to get started.
+
+## Sending Messages
+Refer to [messages](./messages/README.md) for more details on how to send messages using Warb.
+
+## Components
+Refer to [components](./components/README.md) for more details on how Warb components work.

data/docs/components/README.md

@@ -0,0 +1,21 @@
+# Components
+
+Components cannot be used directly, they are used in messages.
+
+Components are used to build complex messages with multiple fields and types.
+
+Here is a table of available components, and where they can be used:
+
+| Component Class                       | Used in Message Types                                                           | Component DOC                                |
+|---------------------------------------|---------------------------------------------------------------------------------|----------------------------------------------|
+| `Warb::Components::Address`           | [Contact](../messages/contact.md)                                               | [Address](./address.md)                      |
+| `Warb::Components::Email`             | [Contact](../messages/contact.md)                                               | [Email](./email.md)                          |
+| `Warb::Components::Name`              | [Contact](../messages/contact.md)                                               | [Name](./name.md)                            |
+| `Warb::Components::Phone`             | [Contact](../messages/contact.md)                                               | [Phone](./phone.md)                          |
+| `Warb::Components::Org`               | [Contact](../messages/contact.md)                                               | [Org](./org.md)                              |
+| `Warb::Components::URL`               | [Contact](../messages/contact.md)                                               | [URL](./url.md)                              |
+| `Warb::Components::CTAAction`         | [Interactive Call to Action URL](../messages/interactive_call_to_action_url.md) | [CTAAction](./cta_action.md)                 |
+| `Warb::Components::ReplyButtonAction` | [Interactive Reply Button](../messages/interactive_reply_button.md)             | [Reply Button Action](./reply_button_action) |
+| `Warb::Components::Row`               | [Interactive List](../messages/interactive_list.md)                             | [Row](./row.md)                              |
+| `Warb::Components::ListAction`        | [Interactive List](../messages/interactive_list.md)                             | [List Action](./list_action.md)              |
+| `Warb::Components::Section`           | [Interactive List](../messages/interactive_list.md)                             | [Section](./section.md)                      |

data/docs/components/address.md

@@ -0,0 +1,68 @@
+# Address
+
+Address, `Warb::Components::Address`, is a component used in the `Contact` message type.
+
+It represents an address with the following fields:
+
+|Attribute       | Type     | Description                                     | Required |
+|----------------|----------|-------------------------------------------------|----------|
+| `street`       | `String` | The street address                              | No       |
+| `city`         | `String` | The city of the address                         | No       |
+| `state`        | `String` | The state of the address                        | No       |
+| `zip`          | `String` | The ZIP code of the address                     | No       |
+| `country`      | `String` | The country of the address                      | No       |
+| `country_code` | `String` | The country code of the address                 | No       |
+| `type`         | `String` | The type of the address (e.g., "HOME", "WORK" ) | No       |
+
+When using the `Warb::Components::Address` component directly, you can set these attributes in the initializer or by assigning them directly to the instance.
+
+```ruby
+address = Warb::Components::Address.new(
+  street: "123 Main St",
+  city: "Springfield",
+  state: "IL",
+  zip: "62701",
+  country: "USA",
+  country_code: "US",
+  type: "HOME"
+)
+```
+
+or
+
+```ruby
+address = Warb::Components::Address.new
+address.street = "123 Main St"
+address.city = "Springfield"
+address.state = "IL"
+address.zip = "62701"
+address.country = "USA"
+```
+
+But is better to use it in the context of a `Contact` message type, where you can add addresses using the `add_address` method:
+
+```ruby
+Warb.contact.dispatch(recipient_number) do |contact|
+  # Adding an address using a block
+  contact.add_address do |address|
+    address.street = "123 Main St"
+    address.city = "Springfield"
+    address.state = "IL"
+    address.zip = "62701"
+    address.country = "USA"
+    address.country_code = "US"
+    address.type = "HOME"
+  end
+
+  # Adding an address with parameters
+  contact.add_address(
+    street: "456 Elm St",
+    city: "Shelbyville",
+    state: "IL",
+    zip: "62565",
+    country: "USA",
+    country_code: "US",
+    type: "WORK"
+  )
+end
+```

data/docs/components/cta_action.md

@@ -0,0 +1,13 @@
+# Call To Action Url Action (CTAAction)
+
+The `CTAAction` component is used to define the action of a call to action URL message.
+
+You don't need to create an instance of `CTAAction` manually, as the `Warb::Resources::InteractiveCalltoActionURL` resource class provides a convenient method to build it, but here are its parameters:
+| Attribute     | Type     | Description                                              | Required |
+|---------------|----------|----------------------------------------------------------|----------|
+| `url`         | `String` | The URL to redirect the user when the button is clicked. | Yes      |
+| `button_text` | `String` | The text to display on the button.                       | Yes      |
+
+The `button_text` content must be, at most, 20 characters long.
+
+See its usage in the [Interactive Call to Action URL Message](../messages/interactive_call_to_action_url.md) documentation.

data/docs/components/email.md

@@ -0,0 +1,40 @@
+# Email
+
+Email, `Warb::Components::Email`, is a component used in the `Contact` message type.
+
+It represents an email address with the following fields:
+
+|Attribute | Type     | Description                                   | Required |
+|----------|----------|-----------------------------------------------|----------|
+| `email`  | `String` | The email address                             | No       |
+| `type`   | `String` | The type of the email (e.g., "HOME", "WORK" ) | No       |
+
+When using the `Warb::Components::Email` component directly, you can set these attributes in the initializer or by assigning them directly to the instance.
+
+```ruby
+address = Warb::Components::Email.new(
+  email: "personal@example.com",
+  type: "HOME"
+)
+```
+or
+
+```ruby
+address = Warb::Components::Email.new(type: "WORK")
+address.email = "work@example.com"
+```
+
+But is better to use it in the context of a `Contact` message type, where you can add emails using the `add_email` method:
+
+```ruby
+Warb.contact.dispatch(recipient_number) do |contact|
+  # Adding an email using a block
+  contact.add_email do |email|
+    email.email = "work@example.com"
+    email.type = "WORK"
+  end
+
+  # Adding an email with parameters
+  contact.add_email(email: "home@example.com", type: "HOME")
+end
+```

data/docs/components/list_action.md

@@ -0,0 +1,29 @@
+# Interactive List Action
+
+The `ListAction` component is used to define the action of an interactive list message.
+
+You don't need to create an instance of `ListAction` manually, as the `Warb::Resources::InteractiveList` resource class provides a convenient method to build it, but here are its parameters:
+
+| Attribute     | Type     | Description                                                                                                          | Required |
+|---------------|----------|----------------------------------------------------------------------------------------------------------------------|----------|
+| button_text   | String   | The text displayed on the button that the user can click to select an option from the list.                          | Yes      |
+| sections      | Array    | An array of [`Warb::Components::Section`](./section.md) instances, each representing a group of options in the list. | Yes      |
+
+The `ListAction` component also provides a `add_section` method to add a section to the action after its creation.
+
+```ruby
+action = Warb::Components::ListAction.new(button_text: "Select")
+section = action.add_section(title: "Languages") # returns a Warb::Components::Section instance
+```
+
+You can also use a block with the `add_section` method to build the section, which is useful for setting its options:
+
+```ruby
+action = Warb::Components::ListAction.new(button_text: "Select")
+section = action.add_section do |section|
+  section.title = "Languages"
+  section.add_row(...) # add options here
+end
+```
+
+Check its complete usage in the [interactive list message documentation](../messages/interactive_list.md).

data/docs/components/name.md

@@ -0,0 +1,49 @@
+# Name
+
+Name, `Warb::Components::Name`, is a component used in the `Contact` message type.
+
+It represents a name with the following fields:
+
+|Attribute         | Type     | Description                                            | Required |
+|------------------|----------|--------------------------------------------------------|----------|
+| `prefix`         | `String` | The prefix used to address the person                  | *No      |
+| `formatted_name` | `String` | The formatted name to be displayed in the contact info | Yes      |
+| `first_name`     | `String` | The contact's first name                               | *No      |
+| `middle_name`    | `String` | The contact's middle name                              | *No      |
+| `last_name`      | `String` | The contact's last name                                | *No      |
+| `suffix`         | `String` | The contact's suffix, if applicable                    | *No      |
+
+**Note**: At least one other attribute **must be provided** along with `formatted_name`.
+
+When using the `Warb::Components::Name` component directly, you can set these attributes in the initializer or by assigning them directly to the instance.
+
+```ruby
+name = Warb::Components::Name.new(
+  formatted_name: "John Doe",
+  prefix: "Mr",
+  first_name: "John",
+  last_name: "Doe"
+)
+```
+or
+
+```ruby
+name = Warb::Components::Name.new
+name.formatted_name = "John Doe"
+name.prefix = "Mr"
+name.first_name = "John"
+name.last_name = "Doe"
+```
+
+But it is better to use it in the context of a `Contact` message type, where you can build the name using the `build_name` method:
+
+```ruby
+Warb.contact.dispatch(recipient_number) do |contact|
+  contact.build_name do |name|
+    name.formatted_name = "John Doe"
+    name.prefix = "Mr"
+    name.first_name = "John"
+    name.last_name = "Doe"
+  end
+end
+```

data/docs/components/org.md

@@ -0,0 +1,42 @@
+# Org
+
+Org, `Warb::Components::Org`, is a component used in the `Contact` message type.
+
+It represents an Organization with the following fields:
+
+|Attribute       | Type     | Description                                   | Required |
+|----------------|----------|-----------------------------------------------|----------|
+| `company`      | `String` | Name of the company where the contact works   | No       |
+| `title`        | `String` | Contact's job title                           | No       |
+| `department`   | `String` | Department within the company                 | No       |
+
+When using the `Warb::Components::Org` component directly, you can set these attributes in the initializer or by assigning them directly to the instance.
+
+```ruby
+org = Warb::Components::Org.new(
+  company: "Example Corp",
+  title: "Software Engineer",
+  department: "Engineering"
+)
+```
+
+or
+
+```ruby
+org = Warb::Components::Org.new
+org.company = "Example Corp"
+org.title = "Software Engineer"
+org.department = "Engineering"
+```
+
+But it is better to use it in the context of a `Contact` message type, where you can build the organization using the `build_org` method:
+
+```ruby
+Warb.contact.dispatch(recipient_number) do |contact|
+  contact.build_org do |org|
+    org.company = "Example Corp"
+    org.title = "Software Engineer"
+    org.department = "Engineering"
+  end
+end
+```

data/docs/components/phone.md

@@ -0,0 +1,57 @@
+# Phone
+
+Phone, `Warb::Components::Phone`, is a component used in the `Contact` message type.
+
+It represents a phone with the following fields:
+
+|Attribute | Type     | Description                                   | Required |
+|----------|----------|-----------------------------------------------|----------|
+| `phone`  | `String` | The phone number                              | No       |
+| `type`   | `String` | The type of the phone (e.g., "HOME", "WORK" ) | No       |
+| `wa_id`  | `String` | The WhatsApp ID associated with the phone     | No       |
+
+The `wa_id` is used to identify the WhatsApp account associated with the given phone number. Generally, it is the same as the phone number, without the `+` sign.
+
+When used, the sent message will allow the recipient to interact directly with the WhatsApp account associated with the `wa_id`:
+
+<img src="../images/contact-with-wa_id.png" width="600">
+
+
+If omitted, or without account associated to the given `wa_id`, the recipient will be able to send a WhatsApp invitation:
+
+<img src="../images/contact-without-wa_id.png" width="600">
+
+When using the `Warb::Components::Phone` component directly, you can set these attributes in the initializer or by assigning them directly to the instance.
+
+```ruby
+phone = Warb::Components::Phone.new(
+  phone: "+1234567890",
+  type: "WORK",
+  wa_id: "1234567890"
+)
+```
+
+or
+
+```ruby
+phone = Warb::Components::Phone.new
+phone.phone = "+1234567890"
+phone.type = "WORK"
+phone.wa_id = "1234567890"
+```
+
+But it is better to use it in the context of a `Contact` message type, where you can add phones using the `add_phone` method:
+
+```ruby
+Warb.contact.dispatch(recipient_number) do |contact|
+  # Adding a phone using a block
+  contact.add_phone do |phone|
+    phone.phone = "+1234567890"
+    phone.type = "WORK"
+    phone.wa_id = "1234567890"
+  end
+
+  # Adding a phone with parameters
+  contact.add_phone(phone: "+0987654321", type: "HOME", wa_id: "0987654321")
+end
+```

data/docs/components/reply_button_action.md

@@ -0,0 +1,32 @@
+# Interactive Reply Button Action
+
+An interactive reply button action allows you to create a set of buttons that, when clicked, send a predefined reply back to the sender.
+
+You don't need to create the buttons manually, as the `Warb::Resources::InteractiveReplyButton` class provides a convenient way to build the action with the buttons texts.
+
+The only `parameter` possible to be set is `buttons_texts`, which is an array of strings representing the texts for each button:
+
+```ruby
+action = Warb::Components::ReplyButtonAction.new(buttons_texts: ["Português", "English", "Español"])
+```
+
+and could be used like this:
+
+```ruby
+Warb.interactive_reply_button.dispatch(recipient_number, action: action) do |message|
+  # Set the header, body, and footer as needed
+end
+```
+
+You can also use the `add_button_text` method to add buttons one by one:
+
+```ruby
+action = Warb::Components::ReplyButtonAction.new
+action.add_button_text("Português")
+action.add_button_text("English")
+action.add_button_text("Español")
+```
+
+Also, note that you can only add up to 3 buttons in a single action
+
+Check the [Interactive Reply Button Message](../messages/interactive_reply_button.md) documentation for more details on how to use this action in a message.

data/docs/components/row.md

@@ -0,0 +1,13 @@
+# Row
+
+Row is a component that represents a single item in a section of an interactive list message. It is used to display an option or choice to the user.
+
+You don't need to create a row by youself, as the `Warb::Components::Section` will handle that for you.
+
+Here are its attributes:
+| Attribute   | Type   | Required | Max Length | Description                                                                 |
+|-------------|--------|----------|------------|-----------------------------------------------------------------------------|
+| title       | String | Yes      | 24         | The title of the row, which is displayed to the user                        |
+| description | String | No       | 72         | A brief description of the row, providing additional context or information |
+
+Check its usage in the [section component documentation](./section.md) or a more complete guide in the [interactive list message documentation](../messages/interactive_list.md)

data/docs/components/section.md

@@ -0,0 +1,30 @@
+# Section
+
+`Warb::Components::Section` is a component that represents a group of items of an interactive list message. It is used to display multiple options, grouped under a common title.
+
+You don't need to create a section by yourself, as the `Warb::Components::ListAction` will handle that for you.
+
+Here are its attributes:
+| Attribute | Type   | Required | Max Length                                             | Description                                    |
+|-----------|--------|----------|--------------------------------------------------------|------------------------------------------------|
+| title     | String | Yes      | 24                                                     | The title of the section                       |
+| rows      | Array  | Yes      | 10 (combining all sections within the message)         | The available options the user can choose from |
+
+The section component instance also offers a `add_row` method to add a row to the section after its creation.
+
+```ruby
+section = Warb::Components::Section.new(title: "Languages")
+
+section.add_row(title: "Português")
+section.add_row(title: "English")
+
+# or using a block
+section.add_row do |row|
+  row.title = "Español"
+  row.description = "Spanish language"
+end
+```
+
+Under the hood, it will create a [`Warb::Components::Row`](./row.md) for each item added to the section.
+
+Check its complete usage in the [interactive list message documentation](../messages/interactive_list.md)

data/docs/components/url.md

@@ -0,0 +1,40 @@
+# URL
+
+URL, `Warb::Components::URL`, is a component used in the `Contact` message type.
+
+It represents an Organization with the following fields:
+
+|Attribute | Type     | Description                                                                          | Required |
+|----------|----------|--------------------------------------------------------------------------------------|----------|
+| `url`    | `String` | Website URL associated with the contact or their company                             | No       |
+| `type`   | `String` | Type of website. For example, company, work, personal, Facebook Page, Instagram, etc | No       |
+
+When using the `Warb::Components::URL` component directly, you can set these attributes in the initializer or by assigning them directly to the instance.
+
+```ruby
+url = Warb::Components::URL.new(
+  url: "https://example.com",
+  type: "company"
+)
+```
+or
+
+```ruby
+url = Warb::Components::URL.new
+url.url = "https://example.com"
+url.type = "company"
+```
+But it is better to use it in the context of a `Contact` message type, where you can build the URL using the `add_url` method:
+
+```ruby
+Warb.contact.dispatch(recipient_number) do |contact|
+  # Adding a URL using a block
+  contact.add_url do |url|
+    url.url = "https://example.com"
+    url.type = "company"
+  end
+
+  # Adding a URL with parameters
+  contact.add_url(url: "https://personal.example.com", type: "personal")
+end
+```