twi 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ca440c616d07a0318bd42e881904d028e8ab6317
-  data.tar.gz: 079f8937ec1046155d9d242b4b9900c786a89f93
+SHA256:
+  metadata.gz: 016ae01fae07b7e70c6f405174016450c862159332b87cacd470478c317817ff
+  data.tar.gz: 0ffcef985cc4256bf2ed9b8a7ad31ce98dd397786b825393d9aada604a1f93c8
 SHA512:
-  metadata.gz: f0cd8ac8913c7858c27dbcb95491bbb19e5fed172353604c83b8196e3caf0d100a6a2275c480da06cee007ec8d96a59f9071d885adb1e6cdf257033700cfd756
-  data.tar.gz: 9e64a5e5fe653bae854be62bb77dab292b6573dedec79a7fda05cecff39b9774459d80188c530493aff84e17f89da5cf0bee1ec4d463ff761ddbb7e6c5cb82eb
+  metadata.gz: 146e6081e40bb06aa2a4c2c404614a8d316ef16e171191b26460121ad2e654092410927e16ba02c819c42f33c3d746d13b306ea0514dc01af5a1ec3c44319181
+  data.tar.gz: 1e46956a86d74ff2077fdcc68b3698e2398b6534be2578dedad528bf6685209691067edf90e09b34f571280537590ff392a5d8b945901a737fe0143c1294f3f8

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+## [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,74 @@
-# 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>
+```
+
+## 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
 
-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/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/event.rb

@@ -0,0 +1,39 @@
+# Enhances the Twilio Ruby gem with an object-oriented approach.
+module Twi
+  # The representation of an event tied to a (clasic) 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 [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.new 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']
+  end
+end

data/lib/twi/lio.rb

@@ -0,0 +1,47 @@
+# 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
+      @sid = ENV['TWILIO_SID']
+      @secret = ENV['TWILIO_SECRET']
+      @conversation_service_sid = ENV['TWILIO_CONVERSATION_SERVICE_SID']
+    end
+
+    # @return [String] the SID to interact with the Twilio API.
+    attr_reader :sid
+
+    # @return [String] the secret to interact with the Twilio API.
+    attr_reader :secret
+
+    # @return [String] the SID of the default Conversation service to use.
+    attr_reader :conversation_service_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.sid, 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_service_sid}/Media/#{id}"
+    end
+  end
+end

data/lib/twi/message.rb

@@ -0,0 +1,65 @@
+# 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
+
+    # @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/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/resource.rb

@@ -0,0 +1,14 @@
+# 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'
+  end
+end

data/lib/twi/version.rb

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

data/lib/twi.rb

@@ -1,5 +1,16 @@
-require "twi/version"
+# frozen_string_literal: true
 
-module Twi
-  # Your code goes here...
-end
+require 'action_controller'
+require 'action_controller/metal/strong_parameters'
+require 'json'
+require 'net/http'
+require 'twilio-ruby'
+
+require 'twi/lio'
+require 'twi/config'
+require 'twi/resource'
+require 'twi/message'
+require 'twi/delivery'
+require 'twi/participant'
+require 'twi/medium'
+require 'twi/event'

metadata

@@ -1,63 +1,69 @@
 --- !ruby/object:Gem::Specification
 name: twi
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.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/delivery.rb
+- lib/twi/event.rb
+- lib/twi/lio.rb
+- lib/twi/medium.rb
+- lib/twi/message.rb
+- lib/twi/participant.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 +71,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