twi 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 016ae01fae07b7e70c6f405174016450c862159332b87cacd470478c317817ff
-  data.tar.gz: 0ffcef985cc4256bf2ed9b8a7ad31ce98dd397786b825393d9aada604a1f93c8
+  metadata.gz: a3da0ed4a9e8746dd8609affeb9cf316a156dafa9a20b0da5e5307c37ea95ad0
+  data.tar.gz: 647d377b97c2fc7951ecd61f3caeb100b5d4ceeb8e1a8d788a5ba0b623a60ef9
 SHA512:
-  metadata.gz: 146e6081e40bb06aa2a4c2c404614a8d316ef16e171191b26460121ad2e654092410927e16ba02c819c42f33c3d746d13b306ea0514dc01af5a1ec3c44319181
-  data.tar.gz: 1e46956a86d74ff2077fdcc68b3698e2398b6534be2578dedad528bf6685209691067edf90e09b34f571280537590ff392a5d8b945901a737fe0143c1294f3f8
+  metadata.gz: 375a364348e16d823426c5670e22a900f52d50d5ee9ac2405f80cd6cd9e3cd7052e20d2d8511f50d44036f579ce273d8a2929908f470fd01aeeaf576e0ec6993
+  data.tar.gz: 97361223e531df80107ed916fa9f81774a9a8694a2e9df8b7acc5dd58468f02c10616df901e798d88f3be3e93b9f1cd4b4c8a3952525ab618378ea1d5a520063

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [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

data/README.md

@@ -55,20 +55,42 @@ 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
 
-1. have a Rails engine with the webhook URLs already set?
 4. have an interface to send and receive SMS with photos
-5. another webhook for conversations
-6. another one to be notified of deliveries
-7. Assistant > create a phone number
 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
-14. return SIDs so we can store them
-15. Set up defaults likw Twi::Lio.sid
-16. Twi.mock = true
 

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_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

@@ -1,16 +1,9 @@
 # Enhances the Twilio Ruby gem with an object-oriented approach.
 module Twi
-  # The representation of an event tied to a (clasic) conversation.
+  # An event tied to a (classic) conversation.
   class Event < Resource
-    # @return [Symbol] what the event is about
-    def target
-      case @params['EventType']
-        when 'onConversationAdded', 'onConversationStateUpdated' then :conversation
-        when 'onParticipantAdded' then :participant
-        when 'onMessageAdded' then :message
-        when 'onDeliveryUpdated' then :delivery
-      end
-    end
+    # @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']
@@ -26,7 +19,7 @@ module Twi
 
     # @return [Array<String>] URLs of image attachments
     def image_urls
-      media = JSON(@params.fetch('Media', '[]')).map { |params| Medium.new params }
+      media = JSON(@params.fetch('Media', '[]')).map { |params| medium_for params }
       media.filter(&:image?).map { |image| image.url }
     end
 
@@ -35,5 +28,29 @@ module Twi
 
     # @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

@@ -30,18 +30,34 @@ module Twi
   class Lio
     # Initialize the global configuration settings defaulting to matching environment variables.
     def initialize
-      @sid = ENV['TWILIO_SID']
+      @api_key = ENV['TWILIO_SID']
       @secret = ENV['TWILIO_SECRET']
-      @conversation_service_sid = ENV['TWILIO_CONVERSATION_SERVICE_SID']
+      @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] the SID to interact with the Twilio API.
-    attr_reader :sid
+    # @return [String] API key - used for basic operations like sending messages.
+    attr_reader :api_key
 
-    # @return [String] the secret to interact with the Twilio API.
+    # @return [String] secret - to authenticate API requests made with +api_key+.
     attr_reader :secret
 
-    # @return [String] the SID of the default Conversation service to use.
-    attr_reader :conversation_service_sid
+    # @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

@@ -18,7 +18,7 @@ module Twi
       http.use_ssl = true
 
       request = Net::HTTP::Get.new(uri.request_uri)
-      request.basic_auth Twi.lio.sid, Twi.lio.secret
+      request.basic_auth Twi.lio.api_key, Twi.lio.secret
       response = http.request(request)
 
       JSON(response.body).dig 'links', 'content_direct_temporary'
@@ -27,7 +27,7 @@ module Twi
   private
 
     def service_url
-      "https://mcs.us1.twilio.com/v1/Services/#{Twi.lio.conversation_service_sid}/Media/#{id}"
+      "https://mcs.us1.twilio.com/v1/Services/#{Twi.lio.conversation_sid}/Media/#{id}"
     end
   end
 end

data/lib/twi/message.rb

@@ -30,6 +30,18 @@ module Twi
       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: [])
       {

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_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

@@ -10,5 +10,13 @@ module Twi
   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,5 +1,5 @@
 # frozen_string_literal: true
 
 module Twi
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/twi.rb

@@ -2,11 +2,14 @@
 
 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'
@@ -14,3 +17,17 @@ 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: twi
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -49,12 +49,26 @@ files:
 - README.md
 - 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
 homepage: https://github.com/claudiob/twi