kapso-client-ruby 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1396532c211130ca44e86a95c6928fed4e9005041326f64bf3bad63ef187eb9
-  data.tar.gz: 563208fa7bd2c5c4d1025e0f05ac400b52aaa2c42bad5c99279803d985eb4bd1
+  metadata.gz: 69afc2eabf951df5ed6149530f2c6512fec01869bcb50f598084db330e5deefd
+  data.tar.gz: f12a18a6582d91ff8806a0ae7d07508f4a0a72db3140a83833101c60e24ce46d
 SHA512:
-  metadata.gz: c90eb6b79eb4a63e0c0c5bff5194b2ae0dbd9b1fb8ceff914b15053b8b3b2ad5a3fdcb85e54e197c241fc760aad7f75b0b841f765cca8e60ca229c574e4340c2
-  data.tar.gz: e1191ea0de205a6590e4f9affa69adf315a007fb0479b89a7a2d0507644f8ccbbdc34ad653be748b62b6c4a0cd1c91f835ec539e31f2bc25399dfccf29eed970
+  metadata.gz: 48ef162b3575307d5a833a7a2dede4b76eec105f020acf0b1da3c4e8c0aa7f1d04f958695530e5bd9254d31372fe740ed40527bec5186b09e9034af966cb902b
+  data.tar.gz: 7b5a2954d39bc0efeb51a8e500eb96ad76e67915a22e1bc0632727cb25fbb1cff3193578d523e13f715ea83164a4e40086408e69e6598c588f17cec40f963ea7

data/.rubocop.yml

@@ -1,82 +1,82 @@
-# frozen_string_literal: true
-
-# RuboCop configuration for WhatsApp Cloud API Ruby SDK
-
-AllCops:
-  TargetRubyVersion: 3.0
-  NewCops: enable
-  Exclude:
-    - 'vendor/**/*'
-    - 'bin/**/*'
-    - 'spec/fixtures/**/*'
-
-# Metrics
-Layout/LineLength:
-  Max: 120
-  AllowedPatterns: ['\A#']
-
-Metrics/MethodLength:
-  Max: 25
-  Exclude:
-    - 'spec/**/*'
-
-Metrics/ClassLength:
-  Max: 150
-  Exclude:
-    - 'spec/**/*'
-
-Metrics/BlockLength:
-  Max: 25
-  Exclude:
-    - 'spec/**/*'
-    - '*.gemspec'
-    - 'Rakefile'
-
-Metrics/AbcSize:
-  Max: 20
-  Exclude:
-    - 'spec/**/*'
-
-# Style
-Style/Documentation:
-  Enabled: false
-
-Style/StringLiterals:
-  EnforcedStyle: single_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: single_quotes
-
-Style/FrozenStringLiteralComment:
-  Enabled: true
-
-Style/ClassAndModuleChildren:
-  EnforcedStyle: compact
-
-# Layout
-Layout/MultilineMethodCallIndentation:
-  EnforcedStyle: indented
-
-Layout/FirstArrayElementIndentation:
-  EnforcedStyle: consistent
-
-Layout/FirstHashElementIndentation:
-  EnforcedStyle: consistent
-
-# Naming
-Naming/FileName:
-  Exclude:
-    - 'whatsapp-cloud-api-ruby.gemspec'
-
-# RSpec specific rules
-RSpec/ExampleLength:
-  Max: 15
-
-RSpec/MultipleExpectations:
-  Max: 5
-
-RSpec/NestedGroups:
-  Max: 4
-
-RSpec/DescribeClass:
+# frozen_string_literal: true
+
+# RuboCop configuration for WhatsApp Cloud API Ruby SDK
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'bin/**/*'
+    - 'spec/fixtures/**/*'
+
+# Metrics
+Layout/LineLength:
+  Max: 120
+  AllowedPatterns: ['\A#']
+
+Metrics/MethodLength:
+  Max: 25
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/ClassLength:
+  Max: 150
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/BlockLength:
+  Max: 25
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+    - 'Rakefile'
+
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - 'spec/**/*'
+
+# Style
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact
+
+# Layout
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+# Naming
+Naming/FileName:
+  Exclude:
+    - 'whatsapp-cloud-api-ruby.gemspec'
+
+# RSpec specific rules
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/DescribeClass:
   Enabled: false

data/CHANGELOG.md

@@ -1,92 +1,263 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.0.0] - 2025-01-09
-
-### Added
-
-- Initial release of WhatsApp Cloud API Ruby SDK
-- Complete WhatsApp Cloud API support with all message types
-- Support for text, image, audio, video, document, sticker, location, and contact messages
-- Interactive message support (buttons, lists, product catalogs)
-- Template message creation and management
-- Media upload, download, and management
-- Phone number registration and verification
-- Call management and permissions (via Kapso proxy)
-- Conversation history and management (via Kapso proxy)
-- Contact management with metadata and tagging (via Kapso proxy)
-- Comprehensive error handling with categorization and retry hints
-- Debug logging with configurable levels
-- Automatic retry logic with exponential backoff
-- Rate limiting detection and handling
-- Support for both Meta Graph API and Kapso proxy
-- Webhook signature verification utilities
-- Extensive documentation and examples
-- Test suite with VCR cassettes
-- Ruby 2.7+ compatibility
-
-### Features
-
-#### Core Messaging
-- Send text messages with URL preview support
-- Send media messages (images, audio, video, documents, stickers)
-- Send location and contact messages
-- Send interactive button and list messages
-- Send template messages with parameter substitution
-- Message reactions (add/remove)
-- Message read status and typing indicators
-
-#### Media Management
-- Upload media files with automatic MIME type detection
-- Download media with authentication handling
-- Get media metadata (size, type, SHA256)
-- Delete media files
-- Save media directly to files
-- Support for different authentication strategies
-
-#### Template Management
-- List, create, update, and delete message templates
-- Template builders for marketing, utility, and authentication templates
-- Component validation and example handling
-- Support for all template types (text, media, interactive)
-
-#### Advanced Features (Kapso Proxy)
-- Message history queries with filtering
-- Conversation management and status updates
-- Contact management with metadata and search
-- Call history and management
-- Analytics and reporting
-- Data export/import capabilities
-
-#### Error Handling
-- Comprehensive error categorization (14+ categories)
-- Intelligent retry recommendations
-- Rate limiting detection with retry-after support
-- Detailed error context and debugging information
-- Custom error classes for different scenarios
-
-#### Developer Experience
-- Extensive documentation with code examples
-- Debug logging with request/response tracing
-- Configurable HTTP client with connection pooling
-- Type-safe response objects
-- Comprehensive test suite
-- Ruby best practices and conventions
-
-### Dependencies
-- faraday (~> 2.0) - HTTP client
-- faraday-multipart (~> 1.0) - Multipart form support
-- mime-types (~> 3.0) - MIME type detection
-- dry-validation (~> 1.10) - Input validation
-
-### Development Dependencies
-- rspec (~> 3.0) - Testing framework
-- webmock (~> 3.18) - HTTP request mocking
-- vcr (~> 6.0) - HTTP interaction recording
-- rubocop (~> 1.50) - Code style checking
-- simplecov (~> 0.22) - Code coverage
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0-alpha.1] - 2025-12-10
+
+### Added Flows API
+
+#### Flows Resource (`client.flows`)
+- **Flow Management**:
+  - `create()` - Create a new WhatsApp Flow
+  - `update()` - Update Flow properties
+  - `delete()` - Delete a Flow
+  - `get()` - Retrieve Flow details
+  - `list()` - List all Flows for a business account
+  
+- **Flow Lifecycle**:
+  - `publish()` - Publish a Flow to production
+  - `deprecate()` - Deprecate an existing Flow
+  - `update_asset()` - Update Flow JSON definition with validation
+  - `preview()` - Get Flow preview URL and expiration
+  - `deploy()` - Idempotent deployment (create/update + publish)
+
+- **Flow Webhooks & Server Utilities**:
+  - `receive_flow_event()` - Decrypt incoming Flow webhook events
+  - `respond_to_flow()` - Encrypt Flow responses for WhatsApp
+  - `download_flow_media()` - Download media from Flow submissions
+  - AES-128-GCM encryption/decryption with RSA key exchange
+  - Automatic payload parsing and validation
+
+#### Messages Enhancement
+- **Flow Messages**:
+  - `send_flow()` - Send interactive Flow messages
+  - Support for Flow CTA buttons
+  - Flow token generation for session tracking
+  - Navigate to specific screens
+  - Flow action payload support
+
+#### New Types
+- `FlowResponse` - Flow creation/update response
+- `FlowData` - Detailed Flow information
+- `FlowAssetResponse` - Asset update validation results
+- `FlowPreviewResponse` - Preview URL and expiration
+- `FlowEventData` - Decrypted Flow webhook events
+- `FlowScreen` - Flow screen configuration
+
+#### New Errors
+- `FlowDecryptionError` - Flow webhook decryption failures
+- `FlowEncryptionError` - Flow response encryption failures
+
+#### Documentation
+- Complete Flows API documentation in README
+- Flow usage examples (`examples/flows_usage.rb`)
+- Webhook handling guide
+- Encryption/decryption examples
+
+### Added Interactive Messages
+
+#### Interactive CTA URL Messages
+- **`send_interactive_cta_url()`** - Send Call-to-Action URL buttons
+  - Support for text, image, video, and document headers
+  - URL validation (HTTP/HTTPS)
+  - Display text max 20 characters
+  - Body text max 1024 characters
+  - Optional footer text (max 60 characters)
+
+#### Catalog Messages
+- **`send_interactive_catalog_message()`** - Send product catalog messages
+  - Thumbnail product selection via retailer ID
+  - Body text validation (max 1024 characters)
+  - Optional footer text (max 60 characters)
+
+#### Enhanced Validations
+- **Header validation** for interactive messages
+  - Text header: max 60 characters
+  - Media headers: require id or link
+  - Type validation (text, image, video, document)
+- **Parameter validation**:
+  - CTA URL: display_text, url, body_text, footer_text
+  - Catalog: body_text, thumbnail_product_retailer_id, footer_text
+- **Comprehensive error messages** with current vs. max values
+
+#### New Private Methods
+- `validate_cta_url_params()` - CTA URL parameter validation
+- `validate_catalog_message_params()` - Catalog message parameter validation
+- `validate_interactive_header()` - Header type and content validation
+- `validate_text_header()` - Text header specific validation
+- `validate_media_header()` - Media header specific validation
+
+#### Documentation
+- Interactive Messages examples (`examples/interactive_messages.rb`)
+- CTA URL usage with all header types
+- Catalog message examples
+- Validation examples and error handling
+- Real-world use cases (e-commerce, events, support, restaurants)
+- README updates with comprehensive examples
+
+### Added Enhanced Features & Validations
+
+#### Enhanced Interactive Button Messages
+- **Media header support** for buttons (previously text-only)
+  - Image headers: Display product images with buttons
+  - Video headers: Show tutorial videos with feedback buttons
+  - Document headers: Attach PDFs/docs with approval buttons
+  - Text headers: Traditional text-only headers (existing)
+- **Button validations**:
+  - Maximum 3 buttons enforced
+  - Minimum 1 button required
+  - Header type validation (text, image, video, document)
+  - Media header content validation (requires id or link)
+
+#### Enhanced Interactive List Messages
+- **Increased body text limit**: 1024 → 4096 characters
+- **Row count validation**: Maximum 10 rows total across all sections
+- **Header restriction**: Text headers only (no media headers for lists)
+- **Improved validations**:
+  - Total row count across all sections enforced
+  - At least 1 row required
+  - Header type validation (text only)
+  - Body text length validation with detailed error messages
+
+#### Updated Validations
+- **Footer handling**: Support for both string and hash formats
+- **Enhanced error messages**: Show current vs. maximum values
+- **Consistent validation**: All interactive message types use shared validators
+
+#### Documentation
+- Enhanced Interactive Messages examples (`examples/enhanced_interactive.rb`)
+- Button header examples (text, image, video, document)
+- List validation examples (4096 chars, 10 rows, text  header)
+- Real-world use cases (product selection, tutorials, document approvals)
+- README updates with detailed examples and validation notes
+
+### Added Advanced Messaging Features
+
+#### Voice Notes Support
+- **Audio voice notes** via `send_audio(voice: true)`
+  - Voice flag for voice note format (recommended: OGG/OPUS)
+  - Regular audio messages when `voice: false` (default)
+  - Perfect for personal messages and support responses
+
+#### Group Messaging Support
+- **`recipient_type` parameter** added to all send methods
+  - `'individual'` - Send to individual users (default)
+  - `'group'` - Send to WhatsApp groups
+  - Group ID format: `XXXXXXXXX@g.us`
+- **Supported for all message types**:
+  - Text, images, videos, documents, audio, stickers
+  - All interactive messages (buttons, lists, CTA URL, etc.)
+  - Templates, reactions, contacts, location
+- **Validation**: Enforces valid recipient types ('individual' or 'group')
+
+#### Location Request Action
+- **`send_interactive_location_request()`** - Request user location
+  - Interactive message asking users to share location
+  - Supports headers (text, image, video, document)
+  - Optional footer text
+  - Perfect for delivery services, meetups, directions
+  - Action: `{ name: 'send_location' }`
+
+#### Updated Core Methods
+- **`build_base_payload()`** - Enhanced with `recipient_type` support
+- **`send_text()`** - Added `recipient_type` parameter
+- **`send_image()`** - Added `recipient_type` parameter
+- **`send_video()`** - Added `recipient_type` parameter
+- **`send_audio()`** - Added `voice` and `recipient_type` parameters
+
+#### Documentation
+- Advanced Messaging examples (`examples/advanced_messaging.rb`)
+- Voice note usage (voice flag, formats)
+- Group messaging examples (text, images, videos)
+- Location request examples (with/without headers)
+- Real-world use cases (support, teams, delivery, education, real estate, community)
+- README updates with all new features
+
+## [1.0.0] - 2025-01-09
+
+### Added
+
+- Initial release of Kapso API Ruby SDK
+- Complete Kapso API support with all message types
+- Support for text, image, audio, video, document, sticker, location, and contact messages
+- Interactive message support (buttons, lists, product catalogs)
+- Template message creation and management
+- Media upload, download, and management
+- Phone number registration and verification
+- Call management and permissions (via Kapso proxy)
+- Conversation history and management (via Kapso proxy)
+- Contact management with metadata and tagging (via Kapso proxy)
+- Comprehensive error handling with categorization and retry hints
+- Debug logging with configurable levels
+- Automatic retry logic with exponential backoff
+- Rate limiting detection and handling
+- Support for both Meta Graph API and Kapso proxy
+- Webhook signature verification utilities
+- Extensive documentation and examples
+- Test suite with VCR cassettes
+- Ruby 2.7+ compatibility
+
+### Features
+
+#### Core Messaging
+- Send text messages with URL preview support
+- Send media messages (images, audio, video, documents, stickers)
+- Send location and contact messages
+- Send interactive button and list messages
+- Send template messages with parameter substitution
+- Message reactions (add/remove)
+- Message read status and typing indicators
+
+#### Media Management
+- Upload media files with automatic MIME type detection
+- Download media with authentication handling
+- Get media metadata (size, type, SHA256)
+- Delete media files
+- Save media directly to files
+- Support for different authentication strategies
+
+#### Template Management
+- List, create, update, and delete message templates
+- Template builders for marketing, utility, and authentication templates
+- Component validation and example handling
+- Support for all template types (text, media, interactive)
+
+#### Advanced Features (Kapso Proxy)
+- Message history queries with filtering
+- Conversation management and status updates
+- Contact management with metadata and search
+- Call history and management
+- Analytics and reporting
+- Data export/import capabilities
+
+#### Error Handling
+- Comprehensive error categorization (14+ categories)
+- Intelligent retry recommendations
+- Rate limiting detection with retry-after support
+- Detailed error context and debugging information
+- Custom error classes for different scenarios
+
+#### Developer Experience
+- Extensive documentation with code examples
+- Debug logging with request/response tracing
+- Configurable HTTP client with connection pooling
+- Type-safe response objects
+- Comprehensive test suite
+- Ruby best practices and conventions
+
+### Dependencies
+- faraday (~> 2.0) - HTTP client
+- faraday-multipart (~> 1.0) - Multipart form support
+- mime-types (~> 3.0) - MIME type detection
+- dry-validation (~> 1.10) - Input validation
+
+### Development Dependencies
+- rspec (~> 3.0) - Testing framework
+- webmock (~> 3.18) - HTTP request mocking
+- vcr (~> 6.0) - HTTP interaction recording
+- rubocop (~> 1.50) - Code style checking
+- simplecov (~> 0.22) - Code coverage
 - yard (~> 0.9) - Documentation generation

data/Gemfile

@@ -1,21 +1,21 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in whatsapp-cloud-api-ruby.gemspec
-gemspec
-
-gem 'rake', '~> 13.0'
-
-group :development, :test do
-  gem 'rspec', '~> 3.12'
-  gem 'webmock', '~> 3.18'
-  gem 'vcr', '~> 6.1'
-  gem 'simplecov', '~> 0.22'
-  gem 'rubocop', '~> 1.50'
-  gem 'rubocop-rspec', '~> 2.20'
-  gem 'yard', '~> 0.9'
-  gem 'pry', '~> 0.14'
-  gem 'pry-byebug', '~> 3.10'
-  gem 'dotenv', '~> 2.8' # For loading .env files in examples
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in whatsapp-cloud-api-ruby.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+
+group :development, :test do
+  gem 'rspec', '~> 3.12'
+  gem 'webmock', '~> 3.18'
+  gem 'vcr', '~> 6.1'
+  gem 'simplecov', '~> 0.22'
+  gem 'rubocop', '~> 1.50'
+  gem 'rubocop-rspec', '~> 2.20'
+  gem 'yard', '~> 0.9'
+  gem 'pry', '~> 0.14'
+  gem 'pry-byebug', '~> 3.10'
+  gem 'dotenv', '~> 2.8' # For loading .env files in examples
 end