warb 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58ff4cfa4904a9a820c4b5906b947b6f5dcbd3e5a3afa76a9e88ed3f83488bb8
-  data.tar.gz: 1edcbcef65fd5f128cb0cf475f4b5c6ae8e4e285a4b57335b80818e0487f874a
+  metadata.gz: c7750b641ab09a5a2ecc79e894e4047a98af4602aebd98aad2edcdf61018142b
+  data.tar.gz: d9b0255c4f0a2c4bc6a6965f21459d971390b7722c4ffec3d2d7c533c649f611
 SHA512:
-  metadata.gz: 43cabbb2bcd395dbbc32eacf0f170e00c5fa913f9edbe4543b9b19f81278648ccae955ac64601182fc468ab02ae81cdb81ae1c07d4601f793dd1645cad28a698
-  data.tar.gz: f7ef031988f7c39be607047ebab9e56d627b848527fce0baa5043f1108a93e378e4e7b6d7df853240bcdba9ccb46b0c0c8ba135833fc31fbccaf01175dab9ba6
+  metadata.gz: d20edff3caa1f062d3c718cebd66dbf1a56392d51148ebe718fa25da9ec2869f8b1af2b82a515250740d5a6ce426064ee85b4db28f14bb27d13f99c919fe7d8a
+  data.tar.gz: 6507de0abb32ef0df3e4d37c1736209d6c85fb76fc890d352be7a9a71f0902f102a5b75f6b3ae11782eaf91e1797c7f10802f691c16e3412e93df8de4e4baddc

data/.rubocop.yml

@@ -1,8 +1,15 @@
+plugins:
+  - rubocop-rspec
+
 AllCops:
   TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - examples/**/*
+    - bin/*
+Style/Documentation:
+  Enabled: false
 
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
+RSpec/NestedGroups:
+  Enabled: false

data/README.md

@@ -9,18 +9,16 @@ A Ruby Gem focused on wrap all the functionalities and use cases of the WhatsApp
 
 ## 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.
+Add `warb` to your bundle
 
-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
+```ruby
+bundle add warb
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+or add it manually to your Gemfile if you prefer.
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+gem 'warb'
 ```
 
 ## Configuration
@@ -90,9 +88,26 @@ Warb.message.dispatch(recipient_number) do |builder|
 end
 ```
 
+### What types of messages can I send?
+
+Warb implements the main types of WhatsApp messages, you can follow the message types [`here`](docs/messages/README.md#messages-types)
+
+examples:
+
+```ruby
+
+warb = Warb.new(...)
+
+warb.message.dispatch(...)
+warb.audio.dispatch(...)
+warb.video.dispatch(...)
+warb.image.dispatch(...)
+...
+```
+
 ### 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).
+We suggest heading to the [`examples`](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.
 
@@ -109,6 +124,14 @@ To enable this kind of flow, you’ll need to know **when** a message is receive
 > ⚠️ **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.
 
+## Deploy
+
+```
+git tag v0.0.2
+git push origin main --tags
+```
+
+
 ## 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.

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

data/docs/README.md

@@ -10,4 +10,7 @@ Refer to [webhook](webhook.md) for more details on how to setup a webhook to get
 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.
+Refer to [components](./components/README.md) for more details on how Warb components work.
+
+## Resources
+Refer to [resources](./resources/README.md) for more details on resources.

data/docs/components/README.md

@@ -18,4 +18,7 @@ Here is a table of available components, and where they can be used:
 | `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)                      |
+| `Warb::Components::Section`           | [Interactive List](../messages/interactive_list.md)                             | [Section](./section.md)                      |
+| `Warb::Components::Button`            | [Template](../messages/template.md)                                             | [Button](./button.md)                        |
+| `Warb::Components::UrlButton`         | [Template](../messages/template.md)                                             | [UrlButton](./url_button.md)                 |
+| `Warb::Components::CopyCodeButton`    | [Template](../messages/template.md)                                             | [CopyCodeButton](./copy_code_button.md)      |

data/docs/components/button.md

@@ -0,0 +1,62 @@
+# Button
+
+`Warb::Components::Button` is a component that represents a generic button used in template messages. It's part of the Components module, which contains reusable parts of complex structures.
+
+It represents a generic button, which can be set with the following attributes:
+
+## Attributes
+|   Attribute  |    Type   | Required |                   Description                 |
+|--------------|-----------|----------|-----------------------------------------------|
+| `index`      | `Integer` |   Yes    | An identifier or position for the button.     |
+| `sub_type`   | `String`  |   Yes    | A more specific classification for the button |
+
+## Common Button Types
+| Button Type   | Template Instance Method     | Params                                   |
+|---------------|------------------------------|------------------------------------------|
+| `quick_reply` | `add_quick_reply_button`     | `index`                                  |
+| `voice_call`  | `add_voice_call_button`      | `index`                                  |
+| `url`         | `add_dynamic_url_button`     | `index`, `text`                          |
+| `copy_code`   | `add_copy_code_button`       | `index`, `coupon_code`                   |
+| `flow`        | `add_flow_button`            | `index`, `flow_token`, `flow_action_data`|
+
+Please, refer to our [templates messaging documentation](../messages/template.md) for more info. You can check the methods to insert a button in the "Adding Buttons" section.
+
+## Examples
+
+### Quick Reply button
+```ruby
+quick_reply = Warb::Components::Button.new(index: 0, sub_type: "quick_reply")
+quick_reply.to_h
+=> {
+     type: "button",
+     sub_type: "quick_reply",
+     index: 0
+   }
+```
+
+### Voice Call button
+```ruby
+voice_call = Warb::Components::Button.new(index: 1, sub_type: "voice_call")
+voice_call.to_h
+=> {
+     type: "button",
+     sub_type: "voice_call",
+     index: 1
+   }
+```
+
+## Usage in Templates
+
+Buttons are typically used within template messages. Here's how to add them:
+
+```ruby
+template = Warb::Resources::Template.new(name: "my_template", language: "en_US")
+
+# Add a quick reply button
+template.add_quick_reply_button(index: 0)
+
+# Add a voice call button
+template.add_voice_call_button(index: 1)
+
+# The buttons will be included in the template's build_payload (as components)
+```

data/docs/components/copy_code_button.md

@@ -0,0 +1,57 @@
+# CopyCodeButton
+
+`Warb::Components::CopyCodeButton` is a component used in template messages for copy code buttons.
+
+## Attributes
+|   Attribute    |    Type   | Required |                   Description                 |
+|----------------|-----------|----------|-----------------------------------------------|
+| `index`        | `Integer` |   Yes    | An identifier or position for the button.     |
+| `sub_type`     | `String`  |   Yes    | Always "copy_code" for this button type       |
+| `coupon_code`  | `String`  |   No     | The coupon code to be copied when button is pressed |
+
+## Examples
+
+### Basic copy code button
+```ruby
+copy_button = Warb::Components::CopyCodeButton.new(index: 0, sub_type: "copy_code", coupon_code: "SAVE20")
+copy_button.to_h
+=> {
+     type: "button",
+     sub_type: "copy_code",
+     index: 0,
+     parameters: [
+       {
+         type: "coupon_code",
+         coupon_code: "SAVE20"
+       }
+     ]
+   }
+```
+
+### Copy code button without coupon code
+```ruby
+copy_button = Warb::Components::CopyCodeButton.new(index: 1, sub_type: "copy_code")
+copy_button.to_h
+=> {
+     type: "button",
+     sub_type: "copy_code",
+     index: 1
+   }
+```
+
+## Usage in Templates
+
+Copy code buttons are typically added to templates using the `add_copy_code_button` method:
+
+```ruby
+template = Warb::Resources::Template.new(name: "my_template", language: "en_US")
+
+# Add a copy code button
+template.add_copy_code_button(index: 0, coupon_code: "SAVE20")
+
+# Or using a block for more complex configuration
+template.add_copy_code_button do |button|
+  button.index = 0
+  button.coupon_code = "SAVE20"
+end
+```

data/docs/components/flow_button.md

@@ -0,0 +1,102 @@
+# FlowButton
+
+```Warb::Components::FlowButton``` is a component used in template messages for flow buttons.
+This button type allows you to link a template directly with a WhatsApp Flow experience.
+
+## Attributes
+| Attribute          | Type      | Required | Description                                                     |
+| ------------------ | --------- | -------- |-----------------------------------------------------------------|
+| `index`            | `Integer` | Yes      | An identifier or position for the button in the template.       |
+| `sub_type`         | `String`  | Yes      | Always `"flow"` for this button type.                           |
+| `flow_token`       | `String`  | No       | If not set, the API defaults to `"unused"`.                     |
+| `flow_action_data` | `Hash`    | No       | A key-value payload passed to the flow as pre-filled form data. |
+
+
+
+## Examples
+###### Basic Flow button with token
+```ruby
+flow_button = Warb::Components::FlowButton.new(
+  index: 0,
+  sub_type: "flow",
+  flow_token: "TOKEN_123"
+)
+
+flow_button.to_h
+=> {
+     type: "button",
+     sub_type: "flow",
+     index: 0,
+     parameters: [
+       {
+         type: "action",
+         action: {
+           flow_token: "TOKEN_123"
+         }
+       }
+     ]
+   }
+```
+
+##### Flow button with token and action data
+```ruby
+flow_button = Warb::Components::FlowButton.new(
+  index: 1,
+  sub_type: "flow",
+  flow_token: "TOKEN_ABC",
+  flow_action_data: { name: "John", cpf: "11122233344" }
+)
+
+flow_button.to_h
+=> {
+     type: "button",
+     sub_type: "flow",
+     index: 1,
+     parameters: [
+       {
+         type: "action",
+         action: {
+           flow_token: "TOKEN_ABC",
+           flow_action_data: { name: "John", cpf: "11122233344" }
+         }
+       }
+     ]
+   }
+```
+
+##### Flow button without optional fields
+```ruby
+flow_button = Warb::Components::FlowButton.new(index: 2, sub_type: "flow")
+flow_button.to_h
+=> {
+     type: "button",
+     sub_type: "flow",
+     index: 2,
+     parameters: [
+       {
+         type: "action",
+         action: {}
+       }
+     ]
+   }
+```
+### Usage in Templates
+
+Flow buttons are typically added to templates using the add_flow_button method:
+
+```ruby
+template = Warb::Resources::Template.new(name: "my_template", language: "en_US")
+
+# Add a flow button with token
+template.add_flow_button(index: 0, flow_token: "TOKEN_123")
+
+# Add a flow button with token and action data
+template.add_flow_button(index: 1, flow_token: "TOKEN_ABC", flow_action_data: { name: "Jane", dob: "1990-01-01" })
+
+# Or using a block for more complex configuration
+template.add_flow_button do |button|
+  button.index = 0
+  button.flow_token = "TOKEN_DYNAMIC"
+  button.flow_action_data = { email: "user@example.com" }
+end
+```

data/docs/components/url_button.md

@@ -0,0 +1,57 @@
+# UrlButton
+
+`Warb::Components::UrlButton` is a component used in template messages, for dynamic url or auth code buttons.
+
+## Attributes
+|   Attribute  |    Type   | Required |                   Description                 |
+|--------------|-----------|----------|-----------------------------------------------|
+| `index`      | `Integer` |   Yes    | An identifier or position for the button.     |
+| `sub_type`   | `String`  |   Yes    | Always "url" for this button type             |
+| `text`       | `String`  |   No     | The URL suffix or text parameter for the button |
+
+## Examples
+
+### Basic URL button
+```ruby
+url_button = Warb::Components::UrlButton.new(index: 0, sub_type: "url", text: "example.com")
+url_button.to_h
+=> {
+     type: "button",
+     sub_type: "url",
+     index: 0,
+     parameters: [
+       {
+         type: "text",
+         text: "example.com"
+       }
+     ]
+   }
+```
+
+### URL button without text parameter
+```ruby
+url_button = Warb::Components::UrlButton.new(index: 1, sub_type: "url")
+url_button.to_h
+=> {
+     type: "button",
+     sub_type: "url",
+     index: 1
+   }
+```
+
+## Usage in Templates
+
+URL buttons are typically added to templates using the `add_dynamic_url_button` method:
+
+```ruby
+template = Warb::Resources::Template.new(name: "my_template", language: "en_US")
+
+# Add a dynamic URL button
+template.add_dynamic_url_button(index: 0, text: "example.com")
+
+# Or using a block for more complex configuration
+template.add_dynamic_url_button do |button|
+  button.index = 0
+  button.text = "example.com"
+end
+```

data/docs/messages/README.md

@@ -71,9 +71,10 @@ Messages are sent using a helper dispatcher and its resource class. Here is a li
 | Video                          | `Warb::Resources::Video`                      | `video`                             | [Video Message](./video.md)                                                   |
 | Special Dispatchers                                                                                                                                                                                  |
 | Indicator                      | `Warb::Resources::Indicator`                  | `indicator`                         | [Indicator Message](./indicator.md)                                           |
+| Template                       | `Warb::Resources::Template`                   | `template`                          | [Template Message](./template.md)                                             |
 
 > Simple Dispatcher doesn't offer any additional functionality, they just send messages.
 
 > Media Dispatchers, aside from sending messages, also provide methods to upload and download media files.
 
-> Special Dispatchers are used for specific purposes, such as sending indicators or reactions.
+> Special Dispatchers are used for specific purposes, such as sending indicators, reactions or templates.

data/docs/messages/flow.md

@@ -1,12 +1,248 @@
 # Flow
 
-Flow is a special type of message. We can summarize it simply as a form.
+Flow is a special type of interactive WhatsApp message that provides a "form-like" experience.
+With ```Warb.flow``` you can send static (navigate) or dynamic (data exchange) flows, both in draft and published modes.
 
-At this point of writing, this gem only supports sending existing flows, and it can only send flows which are in draft.
+Prerequisites (Meta)
+Business Account + Developer Account
+Verified Business to send flows in production WhatsApp (unverified accounts can only test in Meta’s Flow editor)
+For dynamic flows: endpoint + encryption configured in Meta (to handle user responses)
 
-To send flows, you can do as following:
+### Quick Examples
+
+##### Send a static draft flow:
+```ruby
+Warb.flow.dispatch(recipient_number, flow_id: "0000000000000000", mode: "draft", screen: "INITIAL", body: "Open flow")
+```
+
+##### Send a dynamic draft flow:
+```ruby
+Warb.flow.dispatch(recipient_number,
+  flow_id:     "0000000000000000",
+  mode:        "draft",
+  flow_action: "data_exchange",
+  body:        "Open flow"
+)
+```
+
+##### Send a dynamic published flow with custom header, body, and footer:
+```ruby
+Warb.flow.dispatch(recipient_number) do |flow|
+  flow.flow_id     = "0000000000000000"
+  flow.flow_action = "data_exchange"
+  flow.mode        = "published"
+  flow.body        = "Hello! Please follow the instructions."
+  flow.footer      = "Need help? Reply to this message."
+
+  flow.header = {
+    type: "document",
+    document: {
+      link:     "https://example.com/contract.pdf",
+      filename: "contract.pdf"
+    }
+  }
+
+  flow.flow_cta = "Sign"
+end
+```
+
+### Dispatching Flow Messages
 ```ruby
-Warb.flow.dispatch(recipient_number, flow_id: "flow_id", screen: "screen")
+Warb.flow.dispatch(recipient_number, **params, &block)
 ```
+##### Parameters
+| Attribute     | Type     | Required                           | Description                                                 |
+| ------------- | -------- | ---------------------------------- | ----------------------------------------------------------- |
+| `flow_id`     | `String` | Yes                                | The ID of the Flow created in Meta.                         |
+| `body`        | `String` | Yes                                | Body text shown in the Flow message.                        |
+| `flow_action` | `String` | No                                 | `"navigate"` (default) or `"data_exchange"`.                |
+| `mode`        | `String` | Yes if `flow mode == 'draft'`      | `"published"` (default) or `"draft"`.                       |
+| `screen`      | `String` | Yes if `flow_action == "navigate"` | Initial screen to navigate to.                              |
+| `flow_cta`    | `String` | No                                 | Label for the button that opens the Flow.                   |
+| `flow_token`  | `String` | No                                 | Token for dynamic flows (encryption/validation).            |
+| `data`        | `Hash`   | No                                 | Prefill data for navigate flows.                            |
+| `header`      | `Hash`   | No                                 | Optional header (see below).                                |
+| `footer`      | `String` | No                                 | Optional footer text.                                       |
+
+### Supported Headers
+
+You must provide exactly one of the following header types:
 
-`flow_id` must be the ID of the flow and `screen` must be the ID of the first screen of the flow.
+##### Text
+```ruby
+{ type: "text", text: "Flow title" }
+```
+
+##### Image
+```ruby
+{ type: "image", image: { id: "MEDIA_ID" } }
+# or
+{ type: "image", image: { link: "https://example.com/img.jpg" } }
+```
+
+##### Video
+```ruby
+{ type: "video", video: { id: "MEDIA_ID" } }
+# or
+{ type: "video", video: { link: "https://example.com/video.mp4" } }
+```
+
+##### Document
+```ruby
+{ type: "document", document: { id: "MEDIA_ID" } }
+# or
+{ type: "document", document: { link: "https://example.com/file.pdf", filename: "file.pdf" } }
+```
+
+##### Note:
+
+id must be obtained from a media upload (Warb.image/video/document.upload).
+
+link must be a public URL. For documents, filename is required to determine preview capabilities.
+
+### Modes and Actions
+##### mode
+
+"published" (default): Published flow. Allows customizing header, body, footer, and flow_cta.
+
+"draft": Draft flow. Usable via Meta Flow editor and sometimes on WhatsApp, but some elements (like body text and CTA) may be restricted.
+
+##### flow_action
+
+"navigate" (default) → static flow
+Requires screen, can include initial data:
+```ruby
+Warb.flow.dispatch(recipient_number,
+  flow_id: "0000000000000000",
+  screen:  "INITIAL",
+  body:    "Continue",
+  data:    { prefill: { name: "Alice", email: "alice@example.com" } }
+)
+```
+
+"data_exchange" → dynamic flow
+No flow_action_payload (omitted automatically):
+```ruby
+Warb.flow.dispatch(recipient_number,
+  flow_id:     "0000000000000000",
+  flow_action: "data_exchange",
+  body:        "Fill the form",
+)
+```
+
+### Block Building
+
+You can also build flows using a block:
+```ruby
+Warb.flow.dispatch(recipient_number) do |flow|
+  flow.flow_id     = "0000000000000000"
+  flow.flow_action = "data_exchange"
+  flow.mode        = "published"
+  flow.body        = "We need some information"
+
+  flow.header = { type: "text", text: "Registration" }
+  flow.footer = "Thanks!"
+
+  flow.flow_cta   = "Open"
+end
+```
+
+### Validations
+
+Before sending, the gem enforces:
+
+flow_id is required → raises ArgumentError: flow_id is required
+
+body is required → raises ArgumentError: body is required for flow message
+
+If flow_action == "navigate" then screen is required →
+raises ArgumentError: screen is required for flow_action=navigate
+
+The Meta API may return additional errors (invalid parameters, missing fields, etc.), which are raised as Warb::BadRequest, Warb::RequestError, etc.
+
+Example Scenarios
+1) Static / Draft
+```ruby
+Warb.flow.dispatch(recipient_number,
+  flow_id: "0000000000000000",
+  screen:  "INITIAL",
+  mode:    "draft",
+  body:    "Open flow"
+)
+```
+
+2) Dynamic / Draft
+```ruby
+Warb.flow.dispatch(recipient_number,
+  flow_id:     "0000000000000000",
+  flow_action: "data_exchange",
+  mode:        "draft",
+  body:        "Fill the form"
+)
+```
+
+3) Dynamic / Published with Document Header
+```ruby
+Warb.flow.dispatch(recipient_number) do |flow|
+  flow.flow_id     = "0000000000000000"
+  flow.flow_action = "data_exchange"
+  flow.mode        = "published"
+  flow.body        = "Please review and sign the document."
+  flow.footer      = "Reply if you need assistance."
+  flow.flow_cta    = "Sign"
+
+  flow.header = {
+    type: "document",
+    document: {
+      link:     "https://www.thecampusqdl.com/uploads/files/pdf_sample_2.pdf",
+      filename: "pdf_sample_2.pdf"
+    }
+  }
+end
+```
+
+4) Static / Published with Image Header (id) and Prefill Data
+```ruby
+image_id = Warb.image.upload(file_path: "banner.jpg", file_type: "image/jpeg")
+
+Warb.flow.dispatch(recipient_number) do |flow|
+  flow.flow_id = "0000000000000000"
+  flow.mode    = "published"
+  flow.body    = "Open and check your data"
+
+  flow.header = { type: "image", image: { id: image_id } }
+
+  flow.screen = "INITIAL"
+  flow.data   = { prefill: { name: "John", email: "john@example.com" } }
+end
+```
+
+### Generated Payload (Reference)
+
+Example payload produced by the gem:
+```ruby
+{
+  "type": "interactive",
+  "interactive": {
+    "type": "flow",
+    "header": { ... },
+    "body": { "text": "..." },
+    "footer": { "text": "..." },
+    "action": {
+      "name": "flow",
+      "parameters": {
+        "flow_message_version": "3",
+        "flow_id": "....",
+        "flow_action": "navigate" | "data_exchange",
+        "mode": "published" | "draft",
+        "flow_cta": "Open",
+        "flow_token": "TOKEN",
+        "flow_action_payload": {
+          "screen": "INITIAL",
+          "data": { "prefill": { ... } }
+        }
+      }
+    }
+  }
+}
+```