blythedunham-sms_on_rails 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Blythe Dunham
+
+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 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/Manifest

@@ -0,0 +1,101 @@
+app/controllers/admin/sms_on_rails/base_controller.rb
+app/controllers/admin/sms_on_rails/drafts_controller.rb
+app/controllers/admin/sms_on_rails/outbounds_controller.rb
+app/controllers/admin/sms_on_rails/phone_carriers_controller.rb
+app/controllers/admin/sms_on_rails/phone_numbers_controller.rb
+app/controllers/sms_on_rails/creation_support.rb
+app/controllers/sms_on_rails_controller.rb
+app/helpers/admin/sms_on_rails/drafts_helper.rb
+app/helpers/admin/sms_on_rails/phone_carriers_helper.rb
+app/helpers/sms_on_rails/phone_numbers_helper.rb
+app/helpers/sms_on_rails/sms_helper.rb
+app/models/sms_on_rails/draft.rb
+app/models/sms_on_rails/outbound.rb
+app/models/sms_on_rails/phone_carrier.rb
+app/models/sms_on_rails/phone_number.rb
+app/views/admin/sms_on_rails/base/index.html.erb
+app/views/admin/sms_on_rails/drafts/_show.html.erb
+app/views/admin/sms_on_rails/drafts/edit.html.erb
+app/views/admin/sms_on_rails/drafts/index.html.erb
+app/views/admin/sms_on_rails/drafts/new.html.erb
+app/views/admin/sms_on_rails/drafts/send_sms.html.erb
+app/views/admin/sms_on_rails/drafts/show.html.erb
+app/views/admin/sms_on_rails/outbounds/edit.html.erb
+app/views/admin/sms_on_rails/outbounds/index.html.erb
+app/views/admin/sms_on_rails/outbounds/new.html.erb
+app/views/admin/sms_on_rails/outbounds/show.html.erb
+app/views/admin/sms_on_rails/phone_carriers/edit.html.erb
+app/views/admin/sms_on_rails/phone_carriers/index.html.erb
+app/views/admin/sms_on_rails/phone_carriers/new.html.erb
+app/views/admin/sms_on_rails/phone_carriers/show.html.erb
+app/views/admin/sms_on_rails/phone_numbers/edit.html.erb
+app/views/admin/sms_on_rails/phone_numbers/index.html.erb
+app/views/admin/sms_on_rails/phone_numbers/new.html.erb
+app/views/admin/sms_on_rails/phone_numbers/show.html.erb
+app/views/layouts/sms_on_rails/basic.html.erb
+app/views/sms_on_rails/_phone_carrier_form_item.html.erb
+app/views/sms_on_rails/_send_sms.html.erb
+app/views/sms_on_rails/index.html.erb
+app/views/sms_on_rails/send_sms.html.erb
+app/views/sms_on_rails/show.html.erb
+config/routes.rb
+db/data/fixtures/sms_phone_carriers.yml
+db/migrate/sms_on_rails_carrier_tables.rb
+db/migrate/sms_on_rails_model_tables.rb
+db/migrate/sms_on_rails_phone_number_tables.rb
+db/seed_data.rb
+generators/sms_on_rails/commands/inserts.rb
+generators/sms_on_rails/commands/timestamps.rb
+generators/sms_on_rails/runners/add_all_models.rb
+generators/sms_on_rails/runners/dependencies.rb
+generators/sms_on_rails/runners/remove_all_models.rb
+generators/sms_on_rails/runners/sms_on_rails_routes.rb
+generators/sms_on_rails/sms_on_rails_generator.rb
+generators/sms_on_rails/templates/configuration/clickatell.rb
+generators/sms_on_rails/templates/configuration/email_gateway.rb
+generators/sms_on_rails/templates/migrate/schema_migration.rb
+generators/sms_on_rails/templates/migrate/sms_on_rails_update_phone_numbers.rb
+generators/sms_on_rails/templates/phone_number_collision.rb
+generators/sms_on_rails/USAGE
+init.rb
+install.rb
+lib/sms_on_rails/activerecord_extensions/acts_as_deliverable.rb
+lib/sms_on_rails/activerecord_extensions/acts_as_substitutable.rb
+lib/sms_on_rails/activerecord_extensions/has_a_sms_service_provider.rb
+lib/sms_on_rails/activerecord_extensions/lockable_record.rb
+lib/sms_on_rails/all_models.rb
+lib/sms_on_rails/model_support/draft.rb
+lib/sms_on_rails/model_support/outbound.rb
+lib/sms_on_rails/model_support/phone_carrier.rb
+lib/sms_on_rails/model_support/phone_number.rb
+lib/sms_on_rails/model_support/phone_number_associations.rb
+lib/sms_on_rails/schema_helper.rb
+lib/sms_on_rails/service_providers/base.rb
+lib/sms_on_rails/service_providers/clickatell.rb
+lib/sms_on_rails/service_providers/dummy.rb
+lib/sms_on_rails/service_providers/email_gateway.rb
+lib/sms_on_rails/service_providers/email_gateway_support/errors.rb
+lib/sms_on_rails/service_providers/email_gateway_support/sms_mailer/sms_through_gateway.erb
+lib/sms_on_rails/service_providers/email_gateway_support/sms_mailer.rb
+lib/sms_on_rails/util/sms_error.rb
+lib/sms_on_rails.rb
+lib/smsonrails.rb
+Manifest
+MIT-LICENSE
+public/images/sms_on_rails/railsYoDawg.jpg
+public/stylesheets/sms_on_rails.css
+Rakefile
+README
+README.rdoc
+sms_on_rails.gemspec
+tasks/sms_on_rails_tasks.rake
+test/active_record_extensions/delivery_and_locking_test.rb
+test/models/draft_test.rb
+test/models/outbound_test.rb
+test/models/phone_number_test.rb
+test/run.rb
+test/service_providers/abstract_test_support.rb
+test/service_providers/clickatell_test.rb
+test/service_providers/email_gateway_test.rb
+test/test_helper.rb
+uninstall.rb

data/README

@@ -0,0 +1,163 @@
+= SmsOnRails
+
+Sms on Rails provides an interface and ORM framework for sending and storing SMS messages through Email Gateway or with Clickatell HTTPS
+
+The models and underlying architecture extend and include a ton of modules
+and are designed to be configured if necessary. If you do not wish to run the
+vanilla configuration, copy the vendor/plugins/sms_on_rails/lib/models to your
+local models directory.
+
+A lot of care has gone into the locking mechanism to prevent double sends. This
+is a precursor to mass Smsing machine. Further detailed configuration is necessary. Contact
+blythe@snowgiraffe.com if you love grapes.
+
+
+
+== Install
+  script/plugin install git://github.com/blythedunham/smsonrails.git
+
+=== Quick Install
+  script/plugin install git://github.com/blythedunham/smsonrails.git
+ 
+  script/generate sms_on_rails setup --default-service-provider=[provider]
+
+  rake db:migrate
+
+Edit SMS configuration details in <tt>config/environment.rb</tt>. Sign up for clickatell at http://clickatell.com and/or update your mail settings for use with the email gateways.
+
+=== Example Setup
+The following creates a new rails project +dog+ and adds the Sms On Rails plugin. As seen at RailsConf2009
+
+  rails dog --database=mysql
+  mysqladmin -uroot create dog_development
+  cd dog
+  script/plugin install git://github.com/blythedunham/smsonrails
+  script/generate sms_on_rails setup --default-service-provider=clickatell
+  rake db:migrate
+  mate config/environment.rb
+
+
+=== Run Setup Generator
+  script/generate sms_on_rails setup --default-service-provider=[provider]
+
+Running the generator performs several setup steps:
+
+* copy image and stylesheet assets to your public directory
+* generates 3 database migrations (the 2nd and 3rd have a 2 and 3 appended)
+* installs clickatell gem and static_record_cache plugin (for email carriers caching)
+* insert configuration skeleton into environment.rb
+  
+=== Migrate
+Three files are created with different timestamps in <tt>db/migrate</tt>
+* Email Carrier information (email addresses for each carrier like txt.att.net)
+* Phone Number setup. 
+* Draft and Outbound tables
+
+Check them out and then run:
+  rake db:migrate
+
+=== Configure settings
+After running the generator, open up <tt>config/environment.rb</tt> in your rails application. Update the configuration hash maps, added by the generator, with your settings. 
+
+* email gateways - <tt>SmsOnRails::ServiceProviders::EmailGateway.config</tt>. Standard +ActionMailer+ configuration is required for the Email Gateway.
+
+* clickatell http - <tt>SmsOnRails::ServiceProviders::Clickatell.config</tt>. Sign up for an account at http://clickatell.com
+
+Ensure that the correct default provider is selected. 
+  SmsOnRails::ServiceProviders::Base.default_service_provider=
+
+Also make sure that the correct default provider is selected.
+
+<b> Added to environment.rb</b>
+
+  SmsOnRails::ServiceProviders::Clickatell.config = {
+    :api_id => 'api_key',
+    :user_name => 'user_name',
+    :password => 'password'
+  }
+
+  SmsOnRails::ServiceProviders::EmailGateway.config = {
+    :sender => 'youremail address',
+    :subject => 'Default Subject Text'
+    #:bcc => nil,
+    #:mailer_klass => nil,
+  }
+
+  #Default inherits from ActionMailer
+  #SmsOnRails::ServiceProviders::EmailGatewaySupport::SmsMailer.smtp_settings ={}
+
+
+  #Uncomment out your default SMS sender
+  SmsOnRails::ServiceProviders::Base.default_service_provider = SmsOnRails::ServiceProviders::Clickatell.instance
+  #SmsOnRails::ServiceProviders::Base.default_service_provider = SmsOnRails::ServiceProviders::EmailGateway.instance
+
+
+== Avoiding Collisions with existing PhoneNumber class
+If you already have a <tt>PhoneNumber ActiveRecord</tt> class and +phone_number+ database table, you might experience a collision with the SMSOnRails engine. To avoid this, the generator will take the following measures.
+
+=== PhoneNumber Migration
+Instead of creating a new table, the phone number migration created by the generator will add only the columns needed by +SMSOnRails+. Please make sure to check out the migration for errors.
+
+=== PhoneNumber ActiveRecord Class Changes
+The generator will update <tt>PhoneNumber</tt> and add <tt>SmsOnRails::PhoneNumber</tt>
+
+<b>PhoneNumber app/models/sms_on_rails/phone_number.rb</b>
+This file is added and used to point <tt>SmsOnRails::PhoneNumber</tt> point to +PhoneNumber+
+
+
+<b>PhoneNumber app/models/phone_number.rb</b>
+The following two modules are included on your +PhoneNumber+ class:
+* <tt>SmsOnRails::ModelSupport::PhoneNumber</tt> - basic functionality
+* <tt>SmsOnRails::ModelSupport::PhoneNumberAssociations</tt> - associations for +PhoneNumber+
+
+These modules are defined in: 
+  vendor/plugins/smsonrails/lib/sms_on_rails/model_support
+
+Please manually modify your +PhoneNumber+ class to change the associations if you must.
+
+
+
+== Default SMS Routes
+
+Default Links in Your Application
+* Send SMS: http://localhost:3000/sms/new
+* Admin: http://localhost:3000/admin/sms
+  * Draft History:   http://localhost:3000/admin/sms/draft
+  * Phone Numbers:   http://localhost:3000/admin/sms/phone_numbers
+  * Phone Carriers:  http://localhost:3000/admin/sms/phone_carriers
+
+
+== Send Messages
+
+=== Access Service Providers Directly
+All service providers are singletons and can be accessed by their instance
+
+To send a message without validation use +send_message+
+  SmsOnRails::ServiceProviders::<Provider>.instance.send_message '12065551234', 'my message', options
+
+To send a message with validation use +send_to_phone_number+ with a string or  SmsOnRails::PhoneNumber instance
+  SmsOnRails::ServiceProviders<Provider>.instance.send_to_phone_number(number, message, options)
+
+ To send an sms (+Outbound+) (with validation)
+  SmsOnRails::ServiceProviders<Provider>.instance.send_sms(sms, options)
+ However, it is preferred to use the locking mechanism to prevent double messages from being sent
+   sms.deliver!
+
+=== ORM examples:
+Clickatell does not need a carrier
+  SmsOnRails::Outbound.create_sms '12065551234', 'Send this test message', :send_immediately => true
+
+Email gateway needs a carrier specified
+  sms = SmsOnRails::Outbound.create_sms '12065551234', 'Send this test message', :carrier => :att
+  sms.deliver!
+
+
+
+== License
+
+This is MartiniWare. Buy yourself a martini if you like this software.
+
+blythe at snowgiraffe dot com
+http://snowgiraffe.com
+
+Copyright (c) 2009 Blythe Dunham, released under the MIT license

data/README.rdoc

@@ -0,0 +1,211 @@
+= SmsOnRails
+
+Sms on Rails provides an interface and ORM framework for sending and storing SMS messages through Email Gateway or with Clickatell HTTPS
+
+The models and underlying architecture extend and include a ton of modules
+and are designed to be configured if necessary. If you do not wish to run the
+vanilla configuration, copy the <tt>vendor/plugins/sms_on_rails/lib/models</tt> to your
+local models directory or copy <tt>vendor/plugins/sms_on_rails/lib/service_providers</tt> to <tt>lib/service_providers</tt>.
+
+A lot of care has gone into the locking mechanism to prevent double sends. This
+is a precursor to mass Smsing machine. Further detailed configuration is necessary. Contact
+blythe@snowgiraffe.com if you love grapes.
+
+== Install
+
+=== Install Gem
+<b>Add to environment.rb </b>
+  config.gem 'blythedunham-smsonrails', :lib => 'sms_on_rails', :source  => 'http://gems.github.com'
+  config.gem 'clickatell' #If using Clickatell
+
+Vendor the Gem
+  rake gems:install
+  rake gems:unpack
+
+=== Quick Setup (after Install)
+  
+  script/generate sms_on_rails setup --default-service-provider=[provider]
+
+  rake gems:install or rake gems:unpack (if using Clickatell)
+
+  rake db:migrate
+
+=== Alternate Install
+<b>Directly Install Gem</b>
+  gem sources -a http://gems.github.com
+  sudo gem install blythedunham-smsonrails
+
+<b>Plugin</b>
+  script/plugin install git://github.com/blythedunham/smsonrails.git
+
+Edit SMS configuration details in <tt>config/environment.rb</tt>. Sign up for clickatell at http://clickatell.com and/or update your mail settings for use with the email gateways.
+
+=== Example Setup
+The following creates a new rails project +dog+ and adds the Sms On Rails plugin. As seen at RailsConf2009
+
+  rails dog --database=mysql
+  mysqladmin -uroot create dog_development
+  cd dog
+  script/plugin install git://github.com/blythedunham/smsonrails
+  script/generate sms_on_rails setup --default-service-provider=clickatell
+  rake db:migrate
+  mate config/environment.rb
+
+
+=== Run Setup Generator
+  script/generate sms_on_rails setup --default-service-provider=[provider]
+
+Running the generator performs several setup steps:
+
+* copy image and stylesheet assets to your public directory
+* generates 3 database migrations (the 2nd and 3rd have a 2 and 3 appended)
+* installs clickatell gem and static_record_cache plugin (for email carriers caching)
+* insert configuration skeleton into environment.rb
+  
+=== Migrate
+Three files are created with different timestamps in <tt>db/migrate</tt>
+* Email Carrier information (email addresses for each carrier like txt.att.net)
+* Phone Number setup. 
+* Draft and Outbound tables
+
+Check them out and then run:
+  rake db:migrate
+
+=== Configure settings
+After running the generator, open up <tt>config/environment.rb</tt> in your rails application. Update the configuration hash maps, added by the generator, with your settings. 
+
+* email gateways - <tt>SmsOnRails::ServiceProviders::EmailGateway.config</tt>. Standard +ActionMailer+ configuration is required for the Email Gateway.
+
+* clickatell http - <tt>SmsOnRails::ServiceProviders::Clickatell.config</tt>. Sign up for an account at http://clickatell.com
+
+Ensure that the correct default provider is selected. Should be <tt>:email_gateway</tt> or <tt>:clickatell</tt>
+  SmsOnRails::ServiceProviders::Base.set_default_service_provider :clickatell
+
+Also make sure that the correct default provider is selected.
+
+<b> Added to environment.rb</b>
+
+  SmsOnRails::ServiceProviders::Clickatell.config = {
+    :api_id => 'api_key',
+    :user_name => 'user_name',
+    :password => 'password'
+  }
+
+  SmsOnRails::ServiceProviders::EmailGateway.config = {
+    :sender => 'youremail address',
+    :subject => 'Default Subject Text'
+    #:bcc => nil,
+    #:mailer_klass => nil,
+  }
+
+  SmsOnRails::ServiceProviders::Base.set_default_service_provider = :email_gateway
+
+== Avoiding Collisions with existing PhoneNumber class
+If you already have a <tt>PhoneNumber ActiveRecord</tt> class and +phone_number+ database table, you might experience a collision with the SMSOnRails engine. To avoid this, the generator will take the following measures.
+
+=== PhoneNumber Migration
+Instead of creating a new table, the phone number migration created by the generator will add only the columns needed by +SMSOnRails+. Please make sure to check out the migration for errors.
+
+=== PhoneNumber ActiveRecord Class Changes
+The generator will update <tt>PhoneNumber</tt> and add <tt>SmsOnRails::PhoneNumber</tt>
+
+<b>PhoneNumber app/models/sms_on_rails/phone_number.rb</b>
+This file is added and used to point <tt>SmsOnRails::PhoneNumber</tt> point to +PhoneNumber+
+
+
+<b>PhoneNumber app/models/phone_number.rb</b>
+The following two modules are included on your +PhoneNumber+ class:
+* <tt>SmsOnRails::ModelSupport::PhoneNumber</tt> - basic functionality
+* <tt>SmsOnRails::ModelSupport::PhoneNumberAssociations</tt> - associations for +PhoneNumber+
+
+These modules are defined in: 
+  vendor/plugins/smsonrails/lib/sms_on_rails/model_support
+
+Please manually modify your +PhoneNumber+ class to change the associations if you must.
+
+== ActionMailer
+
+You will need to configure ActionMailer in environment.rb if you wish to use the
+Email Gateway. Refer to the Troubleshooting section for more information.
+
+By default, SmsMailer inherits the ActionMailer settings. If your SMS Mailer settings
+differ from the default ActionMailer settings, you can define the new settings in enviroment.rb with:
+  SmsOnRails::ServiceProviders::EmailGatewaySupport::SmsMailer.smtp_settings ={}
+
+
+== Default SMS Routes
+
+Default Links in Your Application
+* Send SMS: http://localhost:3000/sms/new
+* Admin: http://localhost:3000/admin/sms
+  * Draft History:   http://localhost:3000/admin/sms/draft
+  * Phone Numbers:   http://localhost:3000/admin/sms/phone_numbers
+  * Phone Carriers:  http://localhost:3000/admin/sms/phone_carriers
+
+
+== Send Messages
+
+=== Access Service Providers Directly
+All service providers are singletons and can be accessed by their instance
+
+To send a message without validation use +send_message+
+  SmsOnRails::ServiceProviders::<Provider>.instance.send_message '12065551234', 'my message', options
+
+To send a message with validation use +send_to_phone_number+ with a string or  SmsOnRails::PhoneNumber instance
+  SmsOnRails::ServiceProviders<Provider>.instance.send_to_phone_number(number, message, options)
+
+ To send an sms (+Outbound+) (with validation)
+  SmsOnRails::ServiceProviders<Provider>.instance.send_sms(sms, options)
+ However, it is preferred to use the locking mechanism to prevent double messages from being sent
+   sms.deliver!
+
+=== ORM examples:
+Clickatell does not need a carrier
+  SmsOnRails::Outbound.create_sms '12065551234', 'Send this test message', :send_immediately => true
+
+Email gateway needs a carrier specified
+  sms = SmsOnRails::Outbound.create_sms '12065551234', 'Send this test message', :carrier => :att
+  sms.deliver!
+
+
+== Troubleshooting
+
+=== Clickatell
+
+<b> Install Clickatell gem </b>
+If you are using clickatell, please install the clickatell gem with either command:
+  sudo rake gems:unpack
+  sudo rake gems:install
+  sudo gem install clickatell
+
+Possible Error messages:
+* Missing these required gems: clickatell
+* Cannot set default provider to clickatell. Check that support for clickatell exists.
+
+=== Email Gateway
+<b> ActionMailer</b>
+If you are using the email gateways, make sure that your +ActionMailer+ settings are
+configured properly in <tt>environment.rb</tt>. A good test is to send a normal email.
+
+You can also test your settings by adding the line below to your environment.rb file.
+
+  ActionMailer::Base.delivery_method = :test
+
+The message should be print to the log file <tt>log/development.rb</tt> like below:
+  To: 2035553215@vtext.com
+  Subject: Default Subject Text
+  Mime-Version: 1.0
+  Content-Type: text/plain; charset=utf-8
+
+  This is my test message
+
+== Developers
+* Blythe Dunham http://snowgiraffe.com
+
+== Homepage
+* Project Site: http://github.com/blythedunham/smsonrails
+
+== License
+This is MartiniWare. Buy yourself a martini if you like this software! If you like any software that uses this plugin you should also buy yourself a martini. Manhattans are ok too.
+
+Copyright (c) 2009 Blythe Dunham, released under the MIT license