twi 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1f97b3f51774f71277566ba6e50329a019493a1a8f36578aeb1079ae6fe0da1
-  data.tar.gz: 0bc82156d7cd71fd36a62bdf6595146424ba553fb0033981f7eea3d0d227e101
+  metadata.gz: a7531d7fa92db501d0d81a5b9d8ad8108614c63d1260b465a2a0367ef716293c
+  data.tar.gz: 496ac9be22cf2840ae6eeaa5897347ad0402039daad423030b446aae17a8c23e
 SHA512:
-  metadata.gz: 3f2b6f37100f53f86b3f2b7792c15591e2d60d7cb6d9e5d1658862d2af84446d5590ba67846f6c26c788038cc43592f41e0ef01c0f39f8cb72f51fde389c6277
-  data.tar.gz: 00ed8b8c2b73e63547942266681009205140046043b84a75488d41cd91997ae563e42e40084bf74cea037a0fe3b1580dc74cdcd03f237dd84dcdf22e73c53865
+  metadata.gz: e2d906451f3d4c5e8fc2f1cb8fd26b998998bee953d89675594b822b2cad6f55b06b80770540a135d0381d0f537cd16c0f5faada49e0ead42c23cf54302a5460
+  data.tar.gz: c1605aa3aca9c09af360e1ee871c3a9e29787498ad85ba3c38547bda3568f9237d9c6c7c4d45919c7875eb0b08bca0140677aa2145f654cb1e559fb6de34b23b

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [Unreleased]
+
+## [0.9.0] - 2026-09-14
+
+- [New] Place a call with Twi.create_call, telling Twilio where to read its TwiML
+- [New] Add Twi::Call, to read the webhook Twilio reports a call on
+- [New] Add Twi::Call.params_for, to build a call webhook payload in a test
+- [New] Add Twi.mock.call, Twi.mock.call_error and Twi.mock.calls
+
 ## [0.8.0] - 2026-09-11
 
 - [New] Send media with a message: `Twi.create_message media_url:` carries it as an MMS

data/README.md

@@ -1,5 +1,18 @@
 # The enhanced Twilio API Ruby client
 
+## How to install
+
+To install on your system, run:
+
+    gem install twi
+
+To use inside a bundled Ruby project, add this line to the Gemfile:
+
+    gem 'twi', '~> 0.9.0'
+
+This gem follows [Semantic Versioning](https://semver.org). Below 1.0 a minor release may
+break an API, so the pin stops short of 0.10: `bundle update` never crosses one.
+
 ## Available methods
 
 ### Twi::Message
@@ -43,6 +56,36 @@ Twi::Delivery.params_for id: 'SM12', status: 'sent'
  # => { SmsSid: 'SM12', MessgeStatus: 'sent', ErrorCode: nil } 
 ```
 
+### Twi::Call
+
+To place an outbound call, telling Twilio where to read its instructions and where to
+report on how it went:
+
+```ruby
+call = Twi.create_call sender: '8008008000', recipient: '8009007000',
+  url: 'https://example.com/twiml', status_callback: 'https://example.com/calls'
+call.id # => 'CA083e290bef7794c407f14e22a891aa6d'
+call.status # => 'queued'
+```
+
+When receiving an update about a call via webhook:
+
+```ruby
+call = Twi::Call.new params
+call.id # => 'CA083e290bef7794c407f14e22a891aa6d'
+call.status # => 'completed'
+call.digits # => '2'
+call.sender # => '8008008000'
+call.recipient # => '8009007000'
+```
+
+When building a Twilio-like webhook payload:
+
+```ruby
+Twi::Call.params_for id: 'CA12', status: 'completed', digits: '2'
+ # => { CallSid: 'CA12', CallStatus: 'completed', Digits: '2' }
+```
+
 ### Twi::Event
 
 When receiving events about a conversation:
@@ -74,13 +117,34 @@ Use these methods to mock request to Twilio when testing an app:
 Mock an error when creating an incoming phone number:
 
 ```ruby
-Jbr.mock.phone_error = { code: '21452' }
+Twi.mock.phone_error = { code: '21452' }
 ```
 
 Mock successfully creating an incoming phone number:
 
 ```ruby
-Jbr.mock.phone = { id: 'SM083e290bef7794c407f14e65a891aa6d', number: '8009005000' }
+Twi.mock.phone = { id: 'SM083e290bef7794c407f14e65a891aa6d', number: '8009005000' }
+```
+
+### Calls
+
+Mock an error when placing a call:
+
+```ruby
+Twi.mock.call_error = { code: '21215' }
+```
+
+Mock successfully placing a call:
+
+```ruby
+Twi.mock.call = { id: 'CA083e290bef7794c407f14e22a891aa6d', status: 'queued' }
+```
+
+Read back every call placed since the mock was reset, to assert what a suite sent:
+
+```ruby
+Twi.mock.calls # => [{ sender: '8008008000', recipient: '8009007000', url: 'https://example.com/twiml',
+               #      status_callback: 'https://example.com/calls' }]
 ```
 
 

data/lib/twi/call.rb

@@ -0,0 +1,36 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # The representation of an outbound phone call.
+  class Call < Resource
+    # @return [String] unique identifier
+    def id = @params['CallSid']
+
+    # @return [String] call status, one of queued, ringing, in-progress, completed, busy,
+    # no-answer, canceled, failed # TODO: make an enum
+    def status = @params['CallStatus']
+
+    # @return [String, nil] digits the callee pressed in answer to a Gather.
+    def digits = @params['Digits']
+
+    # @return [String] 10-digit phone number placing the call.
+    def sender = remove_prefix_from @params['From']
+
+    # @return [String] 10-digit phone number being called.
+    def recipient = remove_prefix_from @params['To']
+
+    # Places the call, asking Twilio to fetch its instructions from +url+.
+    def create
+      call = api_client.calls.create from: "+1#{@params[:sender]}", to: "+1#{@params[:recipient]}",
+        url: @params[:url], method: 'GET', status_callback: @params[:status_callback]
+
+      @params = { 'CallSid' => call.sid, 'CallStatus' => call.status }
+    rescue Twilio::REST::RestError => error
+      raise Error, code: error.code, message: error.error_message
+    end
+
+    # @return [Hash] the shape of the payload send by Twilio to the callback URL.
+    def self.params_for(id:, status:, digits: nil)
+      { CallSid: id, CallStatus: status, Digits: digits }.compact
+    end
+  end
+end

data/lib/twi/mock/call.rb

@@ -0,0 +1,25 @@
+module Twi
+  class Mock::Call < Call
+    # @return [String] unique identifier
+    def id = @params[:id]
+
+    # @return [String] call status
+    def status = @params[:status]
+
+    # Records the call rather than placing it, and answers whatever the suite arranged.
+    def create
+      Twi.mock.calls << @params.slice(:sender, :recipient, :url, :status_callback)
+
+      if error = Twi.mock.call_error
+        Twi.mock.call_error = nil
+        raise Error, error
+      elsif Twi.mock.call
+        @params[:id] = Twi.mock.call[:id]
+        @params[:status] = Twi.mock.call[:status]
+      else
+        @params[:id] = "CA#{rand}"
+        @params[:status] = 'queued'
+      end
+    end
+  end
+end

data/lib/twi/mock.rb

@@ -1,11 +1,15 @@
 module Twi
   class Mock
     attr_accessor :phone, :phone_error
+    attr_accessor :call, :call_error
     attr_accessor :message, :message_error
     attr_accessor :conversation, :conversation_error
     attr_accessor :medium
 
     # @return [Array<Hash>] every message sent since the mock was reset, in order.
     def messages = @messages ||= []
+
+    # @return [Array<Hash>] every call placed since the mock was reset, in order.
+    def calls = @calls ||= []
   end
 end

data/lib/twi/mocking.rb

@@ -19,6 +19,10 @@ module Twi
       message(...).tap &:create
     end
 
+    def create_call(...)
+      (@mock ? Mock::Call : Call).new(...).tap &:create
+    end
+
     def conversation(...)
       (@mock ? Mock::Conversation : Conversation).new(...)
     end

data/lib/twi/version.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module Twi
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
 end

data/lib/twi.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'action_controller'
 require 'action_controller/metal/strong_parameters'
 require 'active_support/core_ext/enumerable'
@@ -14,6 +12,7 @@ require 'twi/config'
 require 'twi/resource'
 require 'twi/message'
 require 'twi/delivery'
+require 'twi/call'
 require 'twi/participant'
 require 'twi/medium'
 require 'twi/event'
@@ -30,4 +29,5 @@ require 'twi/mock/conversation'
 require 'twi/mock/event'
 require 'twi/mock/medium'
 require 'twi/mock/message'
+require 'twi/mock/call'
 require 'twi/mocking'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: twi
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -37,7 +37,64 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Enhances OpenSSL::HMAC with timestamp.
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Sends messages, places calls and reads the webhooks Twilio answers them
+  with.
 email:
 - claudiob@users.noreply.github.com
 executables: []
@@ -48,6 +105,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/twi.rb
+- lib/twi/call.rb
 - lib/twi/config.rb
 - lib/twi/conversation.rb
 - lib/twi/conversation_event.rb
@@ -60,6 +118,7 @@ files:
 - lib/twi/message.rb
 - lib/twi/message_event.rb
 - lib/twi/mock.rb
+- lib/twi/mock/call.rb
 - lib/twi/mock/conversation.rb
 - lib/twi/mock/event.rb
 - lib/twi/mock/medium.rb
@@ -78,6 +137,7 @@ metadata:
   homepage_uri: https://github.com/claudiob/twi
   source_code_uri: https://github.com/claudiob/twi
   changelog_uri: https://github.com/claudiob/twi
+  documentation_uri: https://rubydoc.info/gems/twi
 rdoc_options: []
 require_paths:
 - lib
@@ -94,5 +154,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: API Signature with timestamped MAC (Message Authentication Code).
+summary: An object-oriented Ruby client for the Twilio API.
 test_files: []