twi 0.0.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ca440c616d07a0318bd42e881904d028e8ab6317
-  data.tar.gz: 079f8937ec1046155d9d242b4b9900c786a89f93
+SHA256:
+  metadata.gz: a3da0ed4a9e8746dd8609affeb9cf316a156dafa9a20b0da5e5307c37ea95ad0
+  data.tar.gz: 647d377b97c2fc7951ecd61f3caeb100b5d4ceeb8e1a8d788a5ba0b623a60ef9
 SHA512:
-  metadata.gz: f0cd8ac8913c7858c27dbcb95491bbb19e5fed172353604c83b8196e3caf0d100a6a2275c480da06cee007ec8d96a59f9071d885adb1e6cdf257033700cfd756
-  data.tar.gz: 9e64a5e5fe653bae854be62bb77dab292b6573dedec79a7fda05cecff39b9774459d80188c530493aff84e17f89da5cf0bee1ec4d463ff761ddbb7e6c5cb82eb
+  metadata.gz: 375a364348e16d823426c5670e22a900f52d50d5ee9ac2405f80cd6cd9e3cd7052e20d2d8511f50d44036f579ce273d8a2929908f470fd01aeeaf576e0ec6993
+  data.tar.gz: 97361223e531df80107ed916fa9f81774a9a8694a2e9df8b7acc5dd58468f02c10616df901e798d88f3be3e93b9f1cd4b4c8a3952525ab618378ea1d5a520063

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+## [0.3.0] - 2026-05-27
+
+- [New] Add Twi::Message#create
+- [New] Add Twi::Conversation#upload
+- [New] Add Twi.event, Twi.mock.medium
+- [New] Add Twi.conversation, Twi.mock.conversation, Twi.mock.conversation_error
+- [New] Add Twi::Event.params_for
+- [New] Add Twi.create_phone, Twi.mock.phone, Twi.mock.phone_error
+- [New] Add Twi::Phone
+
+## [0.2.0] - 2026-05-25
+
+- [New] Twi::Delivery as a wrapper for direct message deliveries
+- [New] Twi::Message as a wrapper for incoming direct messages

data/LICENSE.txt

@@ -1,22 +1,21 @@
-Copyright (c) 2014 claudiob
+The MIT License (MIT)
 
-MIT License
+Copyright (c) 2026 HouseAccount
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,29 +1,96 @@
-# Twi
+# The enhanced Twilio API Ruby client
 
-TODO: Write a gem description
+## Available methods
 
-## Installation
+### Twi::Message
 
-Add this line to your application's Gemfile:
+When receiving an incoming direct message via webhook:
 
-    gem 'twi'
+```ruby
+message = Twi::Message.new params
+message.id # => 'SM083e290bef7794c407f14e22a891aa6d'
+message.content # => 'Hello world'
+message.sender # => '8009007000'
+message.recipient # => '8008008000'
+message.wallflower # nil
+message.opt_in? # false
+message.opt_out? # false
+message.image_urls # => ['https://example.com/image.png']
+```
 
-And then execute:
+When building a Twilio-like webhook payload:
 
-    $ bundle
+```ruby
+Twi::Message.params_for id: 'SM12', content: 'Hello', sender: '8009007000', recipient: '8008008000'
+ # => { MessageSid: 'SM12', Body: 'Hello',From: '+18009007000', To: '+18008008000' } 
+```
 
-Or install it yourself as:
+### Twi::Delivery
 
-    $ gem install twi
+When receiving a delivery notification via webhook:
 
-## Usage
+```ruby
+delivery = Twi::Delivery.new params
+delivery.id # => 'SM083e290bef7794c407f14e22a891aa6d'
+delivery.status # => 'draft'
+delivery.code # => '30006'
+```
 
-TODO: Write usage instructions here
+When building a Twilio-like webhook payload:
 
-## Contributing
+```ruby
+Twi::Delivery.params_for id: 'SM12', status: 'sent'
+ # => { SmsSid: 'SM12', MessgeStatus: 'sent', ErrorCode: nil } 
+```
+
+### Twi::Event
+
+When receiving events about a conversation:
+
+```ruby
+event = Twi::Event.new params
+event.id # => 'SM083e290bef7794c407f14e22a891aa6d'
+event.conversation_id # => 'CH123'
+event.target # => :participant
+event.participant # => #<Participant id: 'SH12', phone: '9008009000', identity: nil>
+```
+
+### Twi::Phone
+
+To create an incoming phone number:
+
+```ruby
+phone = Twi.create_phone area_code:, friendly_name:
+phone.id # => 'SM083e290bef7794c407f14e65a891aa6d'
+phone.number # => '5556667777'
+```
+
+## Available mocks
+
+Use these methods to mock request to Twilio when testing an app:
+
+### Credentials
+
+Mock an error when creating an incoming phone number:
+
+```ruby
+Jbr.mock.phone_error = { code: '21452' }
+```
+
+Mock successfully creating an incoming phone number:
+
+```ruby
+Jbr.mock.phone = { id: 'SM083e290bef7794c407f14e65a891aa6d', number: '8009005000' }
+```
+
+
+## To Do
+
+4. have an interface to send and receive SMS with photos
+8. have an error code URL for each error code and a sid_url
+9. Declare some phones like Twilio.homeowner_phone or Twilio.numbers[:ddd] and a default Twilio.number and similar Twilio.messaging_service
+10. a way to reopen closed conversations
+11. a way to create conversations
+12. and upload pictures in a conversation
+13. x_twilio_webhook_enabled: true
 
-1. Fork it ( https://github.com/[my-github-username]/twi/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request

data/lib/twi/config.rb

@@ -0,0 +1,37 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # Provides methods to read and write global configuration settings.
+  #
+  # A typical usage is to set the +sid+ and +secret+ to interact with Twilio API.
+  #
+  # @example Set the +sid+ and +secret+ to interact with Twilio API:
+  #   Twi.configure do |twilio|
+  #     twilio.sid = 'AC8776d'
+  #     twilio.secret = '588213'
+  #   end
+  #
+  # Note that Twi.configure has precedence over values through with
+  # environment variables (see {Twi::Lio}).
+  #
+  module Config
+    # Yields the global configuration to the given block.
+    #
+    # @example
+    #   Twi.configure do |twilio|
+    #     twilio.sid = 'AC8776d'
+    #   end
+    #
+    # @yield [Twi::Lio] The global configuration.
+    def configure
+      yield lio if block_given?
+    end
+
+    # @return [Twi::Lio] The global configuration.
+    def lio
+      @lio ||= Twi::Lio.new
+    end
+  end
+
+  # @note Config is tauto-loaded in the Twi module to be able to invoke +Twi.configure+.
+  extend Config
+end

data/lib/twi/conversation.rb

@@ -0,0 +1,82 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # The representation of a (classic) group conversation.
+  class Conversation < Resource
+    attr_reader :id, :status
+
+    def create_with(participants:)
+      params = create_params_for participants
+      conversation = conversation_service.conversation_with_participants.create **params
+
+      @id = conversation.sid
+      @status = conversation.state
+    rescue Twilio::REST::RestError => error
+      case error.code
+        when 50438 then raise ExistingConversationError.new(error.error_message)
+        when 50214 then raise TooManyConversationsError.new(error.error_message)
+        else raise
+      end
+    end
+
+    def rename(friendly_name)
+      conversation.update friendly_name: friendly_name
+    end
+
+    def close
+      conversation.update state: :closed
+    end
+
+    def delete
+      conversation.delete
+    end
+
+    def create_message(content:, image_ids: [])
+      conversation.messages.create **message_params_for(content, image_ids)
+    end
+
+    # TODO: Move into Medium -- this method doesn't use anything from this class
+    def upload(file)
+      uri = URI "https://mcs.us1.twilio.com/v1/Services/#{Twi.lio.conversation_sid}/Media"
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      headers = { 'Content-Type' => file.content_type, 'Content-Size' => file.byte_size.to_s }
+      request = Net::HTTP::Post.new uri.request_uri, headers
+      request.basic_auth Twi.lio.api_key, Twi.lio.secret
+      request.body = file.download
+      response = http.request request
+      JSON(response.body)['sid']
+    end
+
+  private
+
+    def conversation
+      conversation_service.conversations @params[:id]
+    end
+
+    def create_params_for(participants)
+      {
+        messaging_service_sid: Twi.lio.messaging_sid, x_twilio_webhook_enabled: 'true',
+        friendly_name: @params[:friendly_name], participant: participant_params_for(participants),
+      }
+    end
+
+    def participant_params_for(participants)
+      participants.map do |participant|
+        phone = "+1#{participant[:phone]}"
+        if participant[:identity]
+          { messaging_binding: { projected_address: phone }, identity: participant[:identity] }
+        else
+          { messaging_binding: { address: phone } }
+        end
+      end.map(&:to_json)
+    end
+
+    def message_params_for(content, image_ids)
+      {
+        author: @params[:author], body: content,
+        media_sid: image_ids, x_twilio_webhook_enabled: 'true',
+      }.compact_blank
+    end
+  end
+end

data/lib/twi/conversation_event.rb

@@ -0,0 +1,10 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # An event signaling a status change for a conversation.
+  class ConversationEvent < Event
+    # @return [Hash] the shape of the payload send by Twilio to the callback URL.
+    def self.params_for(id:, status:)
+      { ConversationSid: id, EventType: 'onConversationChanged', State: status.to_s }
+    end
+  end
+end

data/lib/twi/delivery.rb

@@ -0,0 +1,20 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # The representation of a direct message delivery notification.
+  class Delivery < Resource
+    # @return [String] unique identifier
+    def id = @params['SmsSid']
+
+    # @return [String] delivery status, one of accepted, scheduled, queued, sending, sent,
+    # delivery_unknown, delivered, undelivered, failed # TODO: make an enum
+    def status = @params['MessageStatus']
+
+    # @return [String, nil] error code
+    def code = @params['ErrorCode']
+
+    # @return [Hash] the shape of the payload send by Twilio to the callback URL.
+    def self.params_for(id:, status:, code: nil)
+      { SmsSid: id, MessageStatus: status, ErrorCode: code }
+    end
+  end
+end

data/lib/twi/delivery_event.rb

@@ -0,0 +1,13 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # An event signaling the delivery of a message in a conversation.
+  class DeliveryEvent < Event
+    # @return [Hash] the shape of the payload send by Twilio to the callback URL.
+    def self.params_for(id:, participant_id:, message_id:, status:, code: nil)
+      {
+        ConversationSid: id, EventType: 'onDeliveryChanged', ParticipantSid: participant_id.to_s,
+        MessageSid: message_id, Status: status.to_s, ErrorCode: code
+      }.compact
+    end
+  end
+end

data/lib/twi/error.rb

@@ -0,0 +1,11 @@
+module Twi
+  class Error < StandardError
+  end
+
+  class ExistingConversationError < Error
+    def conversation_id = message[/Conversation (.+)/, 1]
+  end
+
+  class TooManyConversationsError < Error
+  end
+end

data/lib/twi/event.rb

@@ -0,0 +1,56 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # An event tied to a (classic) conversation.
+  class Event < Resource
+    # @return [Symbol] event target type, can be :conversation, :participant, :message, :delivery.
+    def target = @params['EventType'].underscore.split('_').second.to_sym
+
+    # @return [String] conversation state, one of active, inactive, closed, initializing.
+    def status = @params['Status'] || @params['StateTo'] || @params['State']
+
+    # @return [Participant] the participant the event is about (e.g.: joined the conversation).
+    def participant = Participant.new @params
+
+    # @return [String] unique message identifier
+    def id = @params['MessageSid']
+
+    # @return [String, nil] content
+    def content = @params['Body']&.squish
+
+    # @return [Array<String>] URLs of image attachments
+    def image_urls
+      media = JSON(@params.fetch('Media', '[]')).map { |params| medium_for params }
+      media.filter(&:image?).map { |image| image.url }
+    end
+
+    # @return [String] unique conversation identifier
+    def conversation_id = @params['ConversationSid']
+
+    # @return [String, nil] error code
+    def code = @params['ErrorCode']
+
+    # @return [Hash] the shape of the payload send by Twilio to the callback URL.
+    def self.params_for(id:, type:, status: nil, participant: nil)
+      {
+        ConversationSid: id, EventType: "on_#{type}_changed".camelize(:lower),
+        State: status&.to_s,
+      }.merge(participant_params_for participant).compact
+    end
+
+    def self.participant_params_for(participant = nil)
+      if participant
+        if participant[:identity]
+          { ParticipantSid: participant[:id], Identity: participant[:identity] }
+        else
+          { ParticipantSid: participant[:id], 'MessagingBinding.Address' => "+1#{participant[:phone]}" }
+        end
+      else
+        {}
+      end
+    end
+
+  private
+
+    def medium_for(params) = Medium.new params
+  end
+end

data/lib/twi/lio.rb

@@ -0,0 +1,63 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # Provides an object to store global configuration settings.
+  #
+  # This class is not used directly, but by calling {Twi::Config#configure Twi.configure},
+  # which creates and updates a single instance of {Twi::Lio}.
+  #
+  # @example Set the +sid+ and +secret+ to interact with Twilio API:
+  #   Twi.configure do |config|
+  #     twilio.sid = 'AC8776d'
+  #     twilio.secret = '588213'
+  #   end
+  #
+  # @see Twi::Lio for more examples.
+  #
+  # An alternative way to set global configuration settings is by storing
+  # them in the following environment variables:
+  #
+  # * +TWILIO_SID+ to store the Twilio SID
+  # * +TWILIO_SECRET+ to store the Twilio secret
+  # * +TWILIO_CONVERSATION_SERVICE_SID+ to store the Twilio Conversation service ID
+  #
+  # In case both methods are used together,
+  # {Twi::Config#configure Twi.configure} takes precedence.
+  #
+  # @example Set the +sid+ and +secret+ to interact with Twilio API:
+  #   ENV['TWILIO_SID'] = 'AC8776d'
+  #   ENV['TWILIO_SECRET'] = '588213'
+  #
+  class Lio
+    # Initialize the global configuration settings defaulting to matching environment variables.
+    def initialize
+      @api_key = ENV['TWILIO_SID']
+      @secret = ENV['TWILIO_SECRET']
+      @account_sid = ENV['TWILIO_ACCOUNT_SID']
+      @auth_token = ENV['TWILIO_AUTH_TOKEN']
+      @conversation_sid = ENV['TWILIO_CONVERSATION_SERVICE_SID']
+      @messaging_sid = ENV['TWILIO_MESSAGING_SID']
+      @emergency_address_sid = ENV['TWILIO_EMERGENCY_SID']
+    end
+
+    # @return [String] API key - used for basic operations like sending messages.
+    attr_reader :api_key
+
+    # @return [String] secret - to authenticate API requests made with +api_key+.
+    attr_reader :secret
+
+    # @return [String] Account SID - used for advanced operations like creating numbers.
+    attr_reader :account_sid
+
+    # @return [String] OAuth token - to authenticate API requests made with +account_sid+.
+    attr_reader :auth_token
+
+    # @return [String] the SID of the default Conversation service.
+    attr_reader :conversation_sid
+
+    # @return [String] the SID of the default Messaging service.
+    attr_reader :messaging_sid
+
+    # @return [String] the SID of the emergency address.
+    attr_reader :emergency_address_sid
+  end
+end

data/lib/twi/medium.rb

@@ -0,0 +1,33 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # The representation of a medium (image) attached to a message.
+  class Medium < Resource
+    # @return [String] unique identifier
+    def id = @params['Sid']
+
+    # @return [Boolean] whether the medium has the content type of an image.
+    def image? = content_type.match? %r{^image/}
+
+    # @return [String] the content type
+    def content_type = @params['ContentType']
+
+    # @return [String] a URL where the image can be accessed at least for a few minutes.
+    def url
+      uri = URI service_url
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      request = Net::HTTP::Get.new(uri.request_uri)
+      request.basic_auth Twi.lio.api_key, Twi.lio.secret
+      response = http.request(request)
+
+      JSON(response.body).dig 'links', 'content_direct_temporary'
+    end
+
+  private
+
+    def service_url
+      "https://mcs.us1.twilio.com/v1/Services/#{Twi.lio.conversation_sid}/Media/#{id}"
+    end
+  end
+end

data/lib/twi/message.rb

@@ -0,0 +1,77 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # The representation of a direct message.
+  class Message < Resource
+    # @return [String] unique identifier
+    def id = @params['MessageSid']
+
+    # @return [String, nil] content
+    def content = @params['Body']&.squish
+
+    # @return [String] 10-digit phone number sending the SMS.
+    def sender = remove_prefix_from @params['From']
+
+    # @return [String] 10-digit phone number receiving the SMS.
+    def recipient = remove_prefix_from @params['To']
+
+    # @return [String] 10-digit phone number of any CC'd recipient.
+    def wallflower = remove_prefix_from @params['OtherRecipients0']
+
+    # @return [Boolean] whether the sender replied STOP to unsubscribe.
+    def opt_out? = @params['OptOutType'] == 'STOP'
+
+    # @return [Boolean] whether the sender replied START to resubscribe.
+    def opt_in? = @params['OptOutType'] == 'START'
+
+    # @return [Array<String>] URLs of image attachments
+    def image_urls
+      (0...@params['NumMedia'].to_i).filter_map do |index|
+        @params["MediaUrl#{index}"] if @params["MediaContentType#{index}"].match? %r{^image/}
+      end
+    end
+
+    attr_reader :status
+
+    # Sends a message.
+    def create
+      message = api_client.messages.create messaging_service_sid: Twi.lio.messaging_sid.to_s,
+        from: "+1#{@params[:sender]}", to: "+1#{@params[:recipient]}", body: @params[:content]
+
+      @id = message.sid
+      @status = message.status
+      # todo rescue and then set @code
+    end
+
+    # @return [Hash] the shape of the payload send by Twilio to the callback URL.
+    def self.params_for(id:, sender:, recipient:, wallflower: nil, content: nil, opt: nil, media: [])
+      {
+        MessageSid: id,
+        From: "+1#{sender}",
+        To: "+1#{recipient}",
+        Body: content,
+      }.merge media_params_for(media).merge opt_params_for(opt).merge wallflower_params_for(wallflower)
+    end
+
+  private
+
+    def self.media_params_for(media = [])
+      media.each_with_index.inject({ NumMedia: media.size.to_s }) do |hash, (item, index)|
+        url_key = "MediaUrl#{index}".to_sym
+        content_type_key = "MediaContentType#{index}".to_sym
+        hash.merge url_key => item[:url], content_type_key => item[:content_type]
+      end
+    end
+
+    def self.opt_params_for(opt = nil)
+      case opt
+        when :out then { OptOutType: 'STOP' }
+        when :in then { OptOutType: 'START' }
+        else {}
+      end
+    end
+
+    def self.wallflower_params_for(wallflower = nil)
+      wallflower ? { OtherRecipients0: "+1#{wallflower}" } : {}
+    end
+  end
+end

data/lib/twi/message_event.rb

@@ -0,0 +1,21 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # An event signaling a new message in a conversation.
+  class MessageEvent < Event
+    # @return [Hash] the shape of the payload send by Twilio to the callback URL.
+    def self.params_for(id:, participant_id:, content: nil, media: [])
+      {
+        ConversationSid: id, EventType: 'onMessageChanged', ParticipantSid: participant_id.to_s,
+        MessageSid: "SM#{rand}", Body: content, Media: media_params_for(media),
+      }.compact_blank
+    end
+
+  private
+
+    def self.media_params_for(media)
+      media.map do |medium|
+        { Sid: medium[:id], ContentType: medium[:content_type] }
+      end.to_json if media.present?
+    end
+  end
+end

data/lib/twi/mock/conversation.rb

@@ -0,0 +1,29 @@
+module Twi
+  class Mock::Conversation < Conversation
+    def create_with(participants:)
+      if Twi.mock.conversation_error
+        if Twi.mock.conversation_error[:code] == 50438
+          raise ExistingConversationError.new(Twi.mock.conversation_error[:message])
+        elsif Twi.mock.conversation_error[:code] == 50214
+          Twi.mock.conversation_error = nil
+          raise TooManyConversationsError
+        end
+      elsif Twi.mock.conversation
+        @id = Twi.mock.conversation[:id]
+        @status = Twi.mock.conversation[:status]
+      end
+    end
+
+    def upload(file) = 'fake-sid'
+
+    def rename(friendly_name); end
+
+    def close; end
+
+    def delete; end
+
+    def create_message(content:, image_ids: [])
+      Mock::Message.new Twi.mock.message
+    end
+  end
+end

data/lib/twi/mock/event.rb

@@ -0,0 +1,6 @@
+module Twi
+  class Mock::Event < Event
+  private
+    def medium_for(params) = Mock::Medium.new params
+  end
+end

data/lib/twi/mock/medium.rb

@@ -0,0 +1,8 @@
+module Twi
+  class Mock::Medium < Medium
+    # @return [String] a mock URL for the image.
+    def url
+      Twi.mock.medium[:url] if Twi.mock.medium
+    end
+  end
+end

data/lib/twi/mock/message.rb

@@ -0,0 +1,12 @@
+module Twi
+  class Mock::Message < Message
+    # @return [String] unique identifier
+    def id = @params[:id]
+
+    def create
+      @id = "SM#{rand}"
+      @status = 'delivered'
+      # todo rescue and then set @code
+    end
+  end
+end

data/lib/twi/mock/phone.rb

@@ -0,0 +1,12 @@
+module Twi
+  class Mock::Phone < Phone
+    def create
+      if Twi.mock.phone
+        @id = Twi.mock.phone[:id]
+        @number = Twi.mock.phone[:number]
+      elsif Twi.mock.phone_error
+        raise Error, Twi.mock.phone_error
+      end
+    end
+  end
+end

data/lib/twi/mock.rb

@@ -0,0 +1,5 @@
+module Twi
+  class Mock
+    attr_accessor :phone, :phone_error, :message, :conversation, :conversation_error, :medium
+  end
+end

data/lib/twi/mocking.rb

@@ -0,0 +1,33 @@
+module Twi
+  module Mocking
+    def mock
+      @mock ||= Twi::Mock.new
+    end
+
+    def create_phone(...)
+      phone(...).tap &:create
+    end
+
+    def create_message(...)
+      message(...).tap &:create
+    end
+
+    def conversation(...)
+      (@mock ? Mock::Conversation : Conversation).new(...)
+    end
+
+    def event(...)
+      (@mock ? Mock::Event : Event).new(...)
+    end
+
+    def phone(...)
+      (@mock ? Mock::Phone : Phone).new(...)
+    end
+
+    def message(...)
+      (@mock ? Mock::Message : Message).new(...)
+    end
+  end
+
+  extend Mocking
+end

data/lib/twi/participant.rb

@@ -0,0 +1,14 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # The representation of a participant in a (clasic) conversation.
+  class Participant < Resource
+    # @return [String] unique identifier.
+    def id = @params['ParticipantSid']
+
+    # @return [String] 10-digit phone number.
+    def phone = remove_prefix_from @params['MessagingBinding.Address']
+
+    # @return [String, nil] optional identifier.
+    def identity = @params['Identity']
+  end
+end

data/lib/twi/participant_event.rb

@@ -0,0 +1,19 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # An event signaling a participant added to a conversation.
+  class ParticipantEvent < Event
+    # @return [Hash] the shape of the payload send by Twilio to the callback URL.
+    def self.params_for(id:, participant_id:, identity: nil, phone: nil)
+      {
+        ConversationSid: id, EventType: 'onParticipantChanged',
+        ParticipantSid: participant_id.to_s
+      }.merge participant_params_for(identity, phone)
+    end
+
+  private
+
+    def self.participant_params_for(identity, phone)
+      identity ? { Identity: identity } : { 'MessagingBinding.Address' => "+1#{phone}" }
+    end
+  end
+end

data/lib/twi/phone.rb

@@ -0,0 +1,21 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # The representation of a phone number associated to the default messaging service.
+  class Phone < Resource
+    # Create an incoming phone number within the area code and friendly name.
+    def create
+      phone = client.incoming_phone_numbers.create area_code: @params[:area_code],
+        emergency_address_sid: Twi.lio.emergency_address_sid, friendly_name: @params[:friendly_name]
+      messaging_service.phone_numbers.create phone_number_sid: phone.sid
+
+      @id = phone.sid
+      @number = remove_prefix_from phone.phone_number
+    end
+
+    # @return [String] unique identifier of the phone.
+    attr_reader :id
+
+    # @return [String] 10-digit number.
+    attr_reader :number
+  end
+end

data/lib/twi/resource.rb

@@ -0,0 +1,22 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # An abtract class for all Twilio resources.
+  class Resource
+    # @param params [ActionController::Parameters] the payload of Twilio hitting a callback URL.
+    def initialize(params = {})
+      @params = params
+    end
+
+  private
+
+    def remove_prefix_from(number) = number&.strip&.delete_prefix '+1'
+
+    def client = Twilio::REST::Client.new Twi.lio.account_sid, Twi.lio.auth_token
+
+    def api_client = Twilio::REST::Client.new Twi.lio.api_key, Twi.lio.secret
+
+    def messaging_service = client.messaging.v1.services Twi.lio.messaging_sid.to_s
+
+    def conversation_service = client.conversations.v1.services Twi.lio.conversation_sid.to_s
+  end
+end

data/lib/twi/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Twi
-  VERSION = "0.0.1"
+  VERSION = '0.3.0'
 end

data/lib/twi.rb

@@ -1,5 +1,33 @@
-require "twi/version"
+# frozen_string_literal: true
 
-module Twi
-  # Your code goes here...
-end
+require 'action_controller'
+require 'action_controller/metal/strong_parameters'
+require 'active_support/core_ext/enumerable'
+require 'active_support/core_ext/object/blank'
+require 'json'
+require 'net/http'
+require 'twilio-ruby'
+
+require 'twi/lio'
+require 'twi/error'
+require 'twi/config'
+require 'twi/resource'
+require 'twi/message'
+require 'twi/delivery'
+require 'twi/participant'
+require 'twi/medium'
+require 'twi/event'
+require 'twi/conversation_event'
+require 'twi/delivery_event'
+require 'twi/message_event'
+require 'twi/participant_event'
+require 'twi/phone'
+require 'twi/conversation'
+
+require 'twi/mock'
+require 'twi/mock/phone'
+require 'twi/mock/conversation'
+require 'twi/mock/event'
+require 'twi/mock/medium'
+require 'twi/mock/message'
+require 'twi/mocking'

metadata

@@ -1,63 +1,83 @@
 --- !ruby/object:Gem::Specification
 name: twi
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.3.0
 platform: ruby
 authors:
-- claudiob
-autorequire: 
-bindir: bin
+- Claudio Baccigalupo
+bindir: exe
 cert_chain: []
-date: 2014-10-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: actionpack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.6'
-  type: :development
+        version: '0'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: twilio-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Write a longer description. Optional.
+description: Enhances OpenSSL::HMAC with timestamp.
 email:
-- claudiob@gmail.com
+- claudiob@users.noreply.github.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- Gemfile
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/twi.rb
+- lib/twi/config.rb
+- lib/twi/conversation.rb
+- lib/twi/conversation_event.rb
+- lib/twi/delivery.rb
+- lib/twi/delivery_event.rb
+- lib/twi/error.rb
+- lib/twi/event.rb
+- lib/twi/lio.rb
+- lib/twi/medium.rb
+- lib/twi/message.rb
+- lib/twi/message_event.rb
+- lib/twi/mock.rb
+- lib/twi/mock/conversation.rb
+- lib/twi/mock/event.rb
+- lib/twi/mock/medium.rb
+- lib/twi/mock/message.rb
+- lib/twi/mock/phone.rb
+- lib/twi/mocking.rb
+- lib/twi/participant.rb
+- lib/twi/participant_event.rb
+- lib/twi/phone.rb
+- lib/twi/resource.rb
 - lib/twi/version.rb
-- twi.gemspec
-homepage: ''
+homepage: https://github.com/claudiob/twi
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/claudiob/twi
+  source_code_uri: https://github.com/claudiob/twi
+  changelog_uri: https://github.com/claudiob/twi
 rdoc_options: []
 require_paths:
 - lib
@@ -65,17 +85,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.2.2
-signing_key: 
+rubygems_version: 4.0.3
 specification_version: 4
-summary: Write a short summary. Required.
+summary: API Signature with timestamped MAC (Message Authentication Code).
 test_files: []
-has_rdoc: 

data/.gitignore

@@ -1,22 +0,0 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-*.bundle
-*.so
-*.o
-*.a
-mkmf.log

data/Gemfile

@@ -1,4 +0,0 @@
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in twi.gemspec
-gemspec

data/Rakefile

@@ -1,2 +0,0 @@
-require "bundler/gem_tasks"
-

data/twi.gemspec

@@ -1,23 +0,0 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'twi/version'
-
-Gem::Specification.new do |spec|
-  spec.name          = "twi"
-  spec.version       = Twi::VERSION
-  spec.authors       = ["claudiob"]
-  spec.email         = ["claudiob@gmail.com"]
-  spec.summary       = %q{Write a short summary. Required.}
-  spec.description   = %q{Write a longer description. Optional.}
-  spec.homepage      = ""
-  spec.license       = "MIT"
-
-  spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
-
-  spec.add_development_dependency "bundler", "~> 1.6"
-  spec.add_development_dependency "rake"
-end