wittyflow 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3252744ffbeb2f9d18598f0c003bcccdd14fefb68576d31860277bd7bf8abfb
-  data.tar.gz: 7c7aa2a0fd2bc5cd0a42bd9cc82c5ad9af3fee49d74068bf176b6168b0269555
+  metadata.gz: bdc8fbce7e5844bca9a9050807303d746084cc12596b8cd755373633b572111b
+  data.tar.gz: 3483c288145246fb8597f7ee91d0c4fc2b9a83ce4897becd32ff3faa4acb5e0e
 SHA512:
-  metadata.gz: 97d89d9ecbdd332d0031363eb71487cc530772a78de0791eff85721f8df5285b90adaa453e63bc16dc2f0031b2af9b464cd68ed3e8e7ff99379e1e5adeb5f2f0
-  data.tar.gz: e9b79e5733fec9b85e92aa0fc7509b458268ab85807786858a681762e472bac2b1b5b7bf7ac822074978565cb2ae1aedbd95516b2988b37b6ce1494267a05e42
+  metadata.gz: bfcd365cf908f23631e3be46fb32f19b7ccad546f2eb5807f4f6eabb2492ef654bba3b26992efb1315ce8c12cf75b4a26eba9f819d7acc357fdc4ea90c29009e
+  data.tar.gz: cc518905f36f4ad53b98b58f08c161bd1ad7b264576c1443d3e18c7899e26432079c6cc3415b2d60f3efbaa0bc9645990abab8a761f9ee1f2402e412719c2fe4

data/CHANGELOG.md

@@ -0,0 +1,160 @@
+# 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] - 2024-01-XX
+
+### 🚀 Major Release - Complete Rewrite
+
+This is a major release with breaking changes. The gem has been completely rewritten with modern Ruby patterns and production-ready features.
+
+### Added
+
+- **Modern Ruby Support**: Now requires Ruby 3.0+ for better performance and security
+- **Zeitwerk Autoloading**: Automatic code loading for better performance
+- **Comprehensive Error Handling**: Specific error classes for different failure scenarios
+  - `Wittyflow::ConfigurationError` - Invalid configuration
+  - `Wittyflow::ValidationError` - Invalid parameters
+  - `Wittyflow::AuthenticationError` - Invalid credentials
+  - `Wittyflow::NetworkError` - Network timeouts and connectivity issues
+  - `Wittyflow::APIError` - API-specific errors
+- **Retry Logic**: Automatic retry mechanism for network failures with configurable attempts and delays
+- **Global Configuration**: Configure the gem globally for easier Rails integration
+- **Bulk SMS Support**: Send SMS to multiple recipients with `send_bulk_sms` method
+- **Enhanced Phone Number Formatting**: Intelligent handling of various phone number formats
+- **Comprehensive Test Suite**: 90%+ test coverage with RSpec, WebMock, and VCR
+- **Rails Integration Examples**: Detailed examples for Rails applications including:
+  - Service classes
+  - Background jobs with Sidekiq
+  - Model integration
+  - Controller usage
+  - Database logging
+- **Production Features**:
+  - Request timeouts and retries
+  - Proper logging support
+  - User-Agent headers
+  - HTTP connection pooling via HTTParty
+- **Development Tools**:
+  - RuboCop with modern rules
+  - SimpleCov for coverage reporting
+  - YARD for documentation
+  - Guard for automated testing
+
+### Changed
+
+- **BREAKING**: Minimum Ruby version is now 3.0.0
+- **BREAKING**: Main API has changed to use keyword arguments:
+  ```ruby
+  # Old (still works but deprecated)
+  client.send_sms(sender, phone, message)
+  
+  # New
+  client.send_sms(from: sender, to: phone, message: message)
+  ```
+- **BREAKING**: Error handling now uses specific exception classes instead of generic errors
+- Updated HTTParty to latest version (0.21.x)
+- Improved phone number validation and formatting
+- Better response parsing and error messages
+
+### Deprecated
+
+- `Wittyflow::Sms` class is now deprecated in favor of `Wittyflow::Client`
+- Old positional argument methods (still work but show deprecation warnings)
+
+### Removed
+
+- Ruby 2.x support (breaking change)
+- Legacy error handling patterns
+
+### Fixed
+
+- Phone number formatting edge cases
+- Memory leaks in HTTP connections
+- Race conditions in concurrent usage
+- Proper handling of network timeouts
+
+### Security
+
+- Updated all dependencies to latest secure versions
+- Added proper input validation and sanitization
+- Removed potential security vulnerabilities in error messages
+
+## [0.1.0] - 2023-XX-XX
+
+### Added
+- Initial release
+- Basic SMS sending functionality
+- Flash SMS support
+- Account balance checking
+- Message status tracking
+- Basic error handling
+
+### Requirements
+- Ruby 2.0+
+- HTTParty 0.17.x
+
+---
+
+## Migration Guide
+
+### From v0.1.x to v1.0.0
+
+1. **Update Ruby Version**: Ensure you're using Ruby 3.0 or later
+2. **Update Dependencies**: Run `bundle update`
+3. **Update API Calls**: Change to keyword arguments:
+   ```ruby
+   # Before
+   sms = Wittyflow::Sms.new(app_id, app_secret)
+   sms.send_sms("Sender", "0241234567", "Message")
+   
+   # After
+   client = Wittyflow::Client.new(app_id: app_id, app_secret: app_secret)
+   client.send_sms(from: "Sender", to: "0241234567", message: "Message")
+   ```
+4. **Update Error Handling**: Use specific exception classes:
+   ```ruby
+   # Before
+   begin
+     sms.send_sms(...)
+   rescue => e
+     puts "Error: #{e.message}"
+   end
+   
+   # After
+   begin
+     client.send_sms(...)
+   rescue Wittyflow::AuthenticationError => e
+     # Handle auth errors
+   rescue Wittyflow::NetworkError => e
+     # Handle network errors
+   rescue Wittyflow::ValidationError => e
+     # Handle validation errors
+   end
+   ```
+5. **Add Configuration**: Set up global configuration in Rails initializer:
+   ```ruby
+   # config/initializers/wittyflow.rb
+   Wittyflow.configure do |config|
+     config.app_id = ENV['WITTYFLOW_APP_ID']
+     config.app_secret = ENV['WITTYFLOW_APP_SECRET']
+   end
+   ```
+
+### Breaking Changes Summary
+
+- **Ruby 3.0+ Required**: The gem no longer supports Ruby 2.x
+- **Keyword Arguments**: All methods now use keyword arguments instead of positional arguments
+- **New Error Classes**: Generic errors have been replaced with specific error classes
+- **Configuration Changes**: New configuration system with global and instance-level options
+- **HTTParty Update**: Updated to latest version which may have its own breaking changes
+
+### New Features You Can Use
+
+- **Bulk SMS**: Send to multiple recipients at once
+- **Retry Logic**: Automatic retries for failed requests
+- **Better Formatting**: Improved phone number handling
+- **Rails Integration**: Comprehensive examples for Rails apps
+- **Testing Helpers**: Built-in test helpers for easier testing

data/Guardfile

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Wittyflow specific files
+  watch(%r{^lib/wittyflow/(.+)\.rb$}) { |m| "spec/wittyflow/#{m[1]}_spec.rb" }
+  watch(%r{^lib/wittyflow\.rb$}) { "spec/wittyflow_spec.rb" }
+end
+
+guard :rubocop, all_on_start: false, cli: ["--format", "emacs"] do
+  watch(/.+\.rb$/)
+  watch(%r{(?:.+/)?\.rubocop(?:_todo)?\.yml$}) { |m| File.dirname(m[0]) }
+end

data/README.md

@@ -1,8 +1,21 @@
-# Wittyflow
+# Wittyflow Ruby Gem
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/wittyflow`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Gem Version](https://badge.fury.io/rb/wittyflow.svg)](https://badge.fury.io/rb/wittyflow)
+[![Ruby](https://github.com/charlesagyemang/wittyflow_sms_ruby_gem/actions/workflows/ruby.yml/badge.svg)](https://github.com/charlesagyemang/wittyflow_sms_ruby_gem/actions/workflows/ruby.yml)
 
-TODO: Delete this and the text above, and describe your gem
+A production-ready Ruby gem for integrating with the [Wittyflow SMS API](https://wittyflow.com/). Send SMS messages, check delivery status, and manage your account with a clean, modern Ruby interface.
+
+## Features
+
+- 🚀 **Modern Ruby**: Requires Ruby 3.0+ with Zeitwerk autoloading
+- 📱 **Full SMS API**: Send regular SMS, flash SMS, and bulk messaging
+- 🔄 **Retry Logic**: Built-in retry mechanism for network failures
+- 🛡️ **Error Handling**: Comprehensive error types with detailed messages
+- 📊 **Account Management**: Check balance and message delivery status
+- 🌍 **Phone Formatting**: Intelligent phone number formatting for Ghana
+- 🧪 **Well Tested**: 90%+ test coverage with RSpec
+- 📖 **Rails Ready**: Easy integration with Rails applications
+- 🔧 **Configurable**: Global and per-instance configuration options
 
 ## Installation
 
@@ -14,30 +27,469 @@ gem 'wittyflow'
 
 And then execute:
 
-    $ bundle install
+```bash
+$ bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install wittyflow
+```bash
+$ gem install wittyflow
+```
+
+## Configuration
+
+### Global Configuration (Recommended for Rails)
+
+```ruby
+# config/initializers/wittyflow.rb
+Wittyflow.configure do |config|
+  config.app_id = ENV['WITTYFLOW_APP_ID']
+  config.app_secret = ENV['WITTYFLOW_APP_SECRET']
+  config.timeout = 30
+  config.retries = 3
+  config.retry_delay = 1
+  config.default_country_code = "233" # Ghana
+end
+```
+
+### Environment Variables
+
+Create a `.env` file or set environment variables:
+
+```bash
+WITTYFLOW_APP_ID=your_app_id_here
+WITTYFLOW_APP_SECRET=your_app_secret_here
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Basic SMS Sending
+
+```ruby
+# Using global configuration
+client = Wittyflow::Client.new
+
+# Send regular SMS
+response = client.send_sms(
+  from: "YourApp",
+  to: "0241234567",
+  message: "Hello from Wittyflow!"
+)
+
+# Send flash SMS (appears directly on screen)
+response = client.send_flash_sms(
+  from: "YourApp", 
+  to: "0241234567",
+  message: "Urgent: Your verification code is 123456"
+)
+```
+
+### Instance Configuration
+
+```ruby
+# Per-instance configuration
+client = Wittyflow::Client.new(
+  app_id: "your_app_id",
+  app_secret: "your_app_secret",
+  timeout: 60,
+  retries: 5
+)
+
+response = client.send_sms(
+  from: "YourApp",
+  to: "+233241234567",
+  message: "Hello World!"
+)
+```
+
+### Bulk SMS
+
+```ruby
+# Send to multiple recipients
+recipients = ["0241234567", "0241234568", "0241234569"]
+
+results = client.send_bulk_sms(
+  from: "YourApp",
+  to: recipients,
+  message: "Bulk message to all recipients"
+)
+
+# Results is an array with response for each recipient
+results.each_with_index do |result, index|
+  puts "Message to #{recipients[index]}: #{result['status']}"
+end
+```
+
+### Message Status Tracking
+
+```ruby
+# Check delivery status
+status_response = client.message_status("message_id_from_send_response")
+puts "Message status: #{status_response['data']['status']}"
+```
+
+### Account Balance
+
+```ruby
+# Check account balance
+balance_response = client.account_balance
+puts "Balance: #{balance_response['data']['balance']} #{balance_response['data']['currency']}"
+```
+
+## Rails Integration
+
+### 1. SMS Service Class
+
+```ruby
+# app/services/sms_service.rb
+class SmsService
+  include ActiveModel::Model
+  
+  attr_accessor :to, :message, :from
+  
+  validates :to, :message, presence: true
+  validates :from, presence: true, length: { maximum: 11 }
+  
+  def initialize(attributes = {})
+    super
+    @from ||= Rails.application.credentials.sms_sender_id || "YourApp"
+  end
+  
+  def send_sms
+    return false unless valid?
+    
+    begin
+      response = wittyflow_client.send_sms(
+        from: from,
+        to: to,
+        message: message
+      )
+      
+      # Log the response
+      Rails.logger.info "SMS sent successfully: #{response}"
+      
+      # Store in database if needed
+      SmsLog.create!(
+        recipient: to,
+        message: message,
+        sender: from,
+        external_id: response.dig('data', 'message_id'),
+        status: 'sent',
+        response: response
+      )
+      
+      true
+    rescue Wittyflow::Error => e
+      Rails.logger.error "SMS sending failed: #{e.message}"
+      errors.add(:base, "Failed to send SMS: #{e.message}")
+      false
+    end
+  end
+  
+  private
+  
+  def wittyflow_client
+    @wittyflow_client ||= Wittyflow::Client.new
+  end
+end
+```
+
+### 2. Controller Integration
+
+```ruby
+# app/controllers/notifications_controller.rb
+class NotificationsController < ApplicationController
+  before_action :authenticate_user!
+  
+  def send_sms
+    @sms_service = SmsService.new(sms_params)
+    
+    if @sms_service.send_sms
+      flash[:notice] = 'SMS sent successfully!'
+      redirect_to notifications_path
+    else
+      flash[:alert] = @sms_service.errors.full_messages.join(', ')
+      render :new
+    end
+  end
+  
+  private
+  
+  def sms_params
+    params.require(:sms_service).permit(:to, :message, :from)
+  end
+end
+```
+
+### 3. Background Jobs with Sidekiq
+
+```ruby
+# app/jobs/send_sms_job.rb
+class SendSmsJob < ApplicationJob
+  queue_as :default
+  
+  retry_on Wittyflow::NetworkError, wait: :exponentially_longer, attempts: 3
+  retry_on Wittyflow::APIError, wait: 30.seconds, attempts: 2
+  
+  def perform(recipient, message, sender = nil)
+    client = Wittyflow::Client.new
+    
+    response = client.send_sms(
+      from: sender || Rails.application.credentials.sms_sender_id,
+      to: recipient,
+      message: message
+    )
+    
+    # Update database record if needed
+    SmsLog.find_by(recipient: recipient, message: message)
+           &.update!(external_id: response.dig('data', 'message_id'))
+  end
+end
+
+# Usage in controllers or models
+SendSmsJob.perform_later(user.phone, "Welcome to our service!", "YourApp")
+```
+
+### 4. Model Integration
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  after_create :send_welcome_sms
+  
+  def send_sms(message, sender = nil)
+    return false unless phone.present?
+    
+    SmsService.new(
+      to: phone,
+      message: message,
+      from: sender
+    ).send_sms
+  end
+  
+  def send_verification_code
+    code = generate_verification_code
+    update(verification_code: code)
+    
+    send_sms("Your verification code is: #{code}")
+  end
+  
+  private
+  
+  def send_welcome_sms
+    SendSmsJob.perform_later(
+      phone,
+      "Welcome to #{Rails.application.class.module_parent_name}! Thanks for joining us.",
+      "YourApp"
+    )
+  end
+  
+  def generate_verification_code
+    SecureRandom.random_number(999999).to_s.rjust(6, '0')
+  end
+end
+```
+
+### 5. Database Logging
+
+```ruby
+# db/migrate/xxx_create_sms_logs.rb
+class CreateSmsLogs < ActiveRecord::Migration[7.0]
+  def change
+    create_table :sms_logs do |t|
+      t.string :recipient, null: false
+      t.text :message, null: false
+      t.string :sender
+      t.string :external_id
+      t.string :status, default: 'pending'
+      t.json :response
+      t.timestamps
+    end
+    
+    add_index :sms_logs, :recipient
+    add_index :sms_logs, :external_id
+    add_index :sms_logs, :status
+  end
+end
+
+# app/models/sms_log.rb
+class SmsLog < ApplicationRecord
+  validates :recipient, :message, presence: true
+  
+  enum status: {
+    pending: 'pending',
+    sent: 'sent',
+    delivered: 'delivered',
+    failed: 'failed'
+  }
+  
+  scope :recent, -> { order(created_at: :desc) }
+  scope :for_recipient, ->(phone) { where(recipient: phone) }
+end
+```
+
+## Phone Number Formats
+
+The gem automatically handles various phone number formats for Ghana:
+
+```ruby
+# All of these formats work:
+client.send_sms(from: "App", to: "0241234567", message: "Hello")      # Local with 0
+client.send_sms(from: "App", to: "241234567", message: "Hello")       # Local without 0  
+client.send_sms(from: "App", to: "+233241234567", message: "Hello")   # International
+client.send_sms(from: "App", to: "233241234567", message: "Hello")    # Country code only
+
+# They all get formatted to: "233241234567"
+```
+
+## Error Handling
+
+The gem provides specific error types for different scenarios:
+
+```ruby
+begin
+  client.send_sms(from: "App", to: "0241234567", message: "Hello")
+rescue Wittyflow::AuthenticationError => e
+  # Invalid app_id or app_secret
+  puts "Authentication failed: #{e.message}"
+rescue Wittyflow::ValidationError => e
+  # Invalid parameters (missing required fields, etc.)
+  puts "Validation error: #{e.message}"
+rescue Wittyflow::NetworkError => e
+  # Network timeout or connection issues
+  puts "Network error: #{e.message}"
+rescue Wittyflow::APIError => e
+  # API-specific errors (rate limiting, server errors)
+  puts "API error: #{e.message}"
+rescue Wittyflow::Error => e
+  # Any other Wittyflow-related error
+  puts "Wittyflow error: #{e.message}"
+end
+```
+
+## Testing
+
+### With RSpec
+
+```ruby
+# spec/support/wittyflow_helpers.rb
+module WittyflowHelpers
+  def stub_wittyflow_success(response_data = {})
+    allow_any_instance_of(Wittyflow::Client)
+      .to receive(:send_sms)
+      .and_return({
+        'status' => 'success',
+        'data' => { 'message_id' => 'msg_123' }.merge(response_data)
+      })
+  end
+  
+  def stub_wittyflow_error(error_class = Wittyflow::APIError, message = "API Error")
+    allow_any_instance_of(Wittyflow::Client)
+      .to receive(:send_sms)
+      .and_raise(error_class, message)
+  end
+end
+
+# In your specs
+RSpec.configure do |config|
+  config.include WittyflowHelpers
+end
+
+# spec/services/sms_service_spec.rb
+RSpec.describe SmsService do
+  describe '#send_sms' do
+    let(:service) { described_class.new(to: '0241234567', message: 'Test') }
+    
+    context 'when API call succeeds' do
+      before { stub_wittyflow_success }
+      
+      it 'returns true' do
+        expect(service.send_sms).to be true
+      end
+    end
+    
+    context 'when API call fails' do
+      before { stub_wittyflow_error(Wittyflow::NetworkError, 'Network timeout') }
+      
+      it 'returns false and adds error' do
+        expect(service.send_sms).to be false
+        expect(service.errors[:base]).to include('Failed to send SMS: Network timeout')
+      end
+    end
+  end
+end
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+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.
+
+### Available Rake Tasks
+
+```bash
+rake spec          # Run all tests
+rake rubocop       # Run RuboCop linter
+rake quality       # Run all quality checks (tests + linting)
+rake coverage      # Generate test coverage report
+rake doc           # Generate YARD documentation
+```
+
+### Contributing
 
-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).
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Write tests for your changes
+4. Ensure all tests pass (`rake quality`)
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create a Pull Request
 
-## Contributing
+## Changelog
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/wittyflow. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/wittyflow/blob/master/CODE_OF_CONDUCT.md).
+### v1.0.0 (Latest)
+
+- **Breaking Changes**: Requires Ruby 3.0+
+- Complete rewrite with modern Ruby patterns
+- Added comprehensive error handling with specific error types
+- Added retry logic for network failures
+- Added bulk SMS support
+- Added extensive test suite (90%+ coverage)
+- Added Rails integration examples
+- Added global configuration support
+- Improved phone number formatting
+- Added Zeitwerk autoloading
+
+### v0.1.0 (Legacy)
+
+- Basic SMS sending functionality
+- Minimal error handling
+- Ruby 2.0+ support
+
+## Migration from v0.x
+
+If you're upgrading from v0.x, here are the key changes:
+
+```ruby
+# Old way (still works but deprecated)
+sms = Wittyflow::Sms.new(app_id, app_secret)
+sms.send_sms(sender, phone, message)
+
+# New way
+client = Wittyflow::Client.new(app_id: app_id, app_secret: app_secret)
+client.send_sms(from: sender, to: phone, message: message)
+```
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
+## Support
+
+- 📧 Email: micnkru@gmail.com
+- 🐛 [Report Issues](https://github.com/charlesagyemang/wittyflow_sms_ruby_gem/issues)
+- 📖 [Documentation](https://github.com/charlesagyemang/wittyflow_sms_ruby_gem)
+
 ## Code of Conduct
 
-Everyone interacting in the Wittyflow project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/wittyflow/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Wittyflow project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/charlesagyemang/wittyflow_sms_ruby_gem/blob/main/CODE_OF_CONDUCT.md).