active_mailbox 0.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Joshua Priddle
+
+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/README.markdown

@@ -0,0 +1,215 @@
+# ActiveMailbox
+
+ActiveMailbox provides a simple API and command line utility to work with
+voicemail boxes and voicemails generated by Asterisk.
+
+
+## Command line usage via active_mailbox
+
+ActiveMailbox includes a command line tool which administrators can use to
+perform maintenance on a user's mailbox.
+
+The command takes **three** arguments: the action (OPTION), the context
+defined in voicemail.conf (CONTEXT), and the user's phone number (MAILBOX)
+
+    Usage: active_mailbox [OPTION] MAILBOX
+
+    Mailbox Options:
+            --context                    Look for [MAILBOX] in [CONTEXT]
+            --delete                     Delete [MAILBOX] and all messages
+            --sort                       Sort messages in [MAILBOX] (recursive)
+
+    Cleanup Options:
+            --clean-ghosts               Cleanup 'ghost' messages
+            --clean-stale                Cleanup messages older than 30 days
+            --clean-mp3s                 Cleanup [MAILBOX]/.mp3 directory
+            --purge                      Remove all messages, but leave [MAILBOX] folders intact
+
+    Greeting Options:
+            --delete-temp                Delete [MAILBOX]/temp.wav
+            --delete-unavail             Delete [MAILBOX]/unavail.wav
+            --delete-busy                Delete [MAILBOX]/busy.wav
+
+    General Options:
+        -h, --help                       Show this message
+        -v, --version                    Show version
+
+
+### Example Command line usage
+
+#### Delete unavailable greeting
+
+    active_mailbox --delete-unavail 15183332220
+
+
+#### Delete temp greeting
+
+    active_mailbox --delete-temp 15183332220
+
+
+#### Purge mailbox (deletes all messages, leaves folders intact)
+
+    active_mailbox --purge 15183332220
+
+
+#### Delete messages older than 30 days
+
+    active_mailbox --clean-stale 15183332220
+
+
+#### Delete mailbox
+
+    active_mailbox --delete 15183332222
+
+
+#### Delete 'ghost' messages
+
+Ghost voicemails happen if a message's txt file exists, but the
+corresponding wav file does not. Example:
+
+    tree 518/15183332225/INBOX
+        518/15183332225/INBOX
+        |-- msg0000.txt
+        |-- msg0000.wav
+        `-- msg0002.txt
+
+Run `active_mailbox --clean-ghosts` to clear the offending txt files.
+
+    active_mailbox --clean-ghosts 518 15183332220
+
+Observe the results:
+
+    tree 518/15183332225/INBOX
+        518/15183332225/INBOX
+        |-- msg0000.txt
+        `-- msg0000.wav
+
+#### Sorting
+
+If voicemails are manually deleted, the INBOX order can be out of sync, as
+depicted below:
+
+    tree 518/15183332225/INBOX
+        518/15183332225/INBOX
+        |-- msg0000.txt
+        |-- msg0000.wav
+        |-- msg0002.txt
+        |-- msg0002.wav
+        |-- msg0006.txt
+        |-- msg0006.wav
+        |-- msg0009.txt
+        `-- msg0009.wav
+
+Sort the messages so they play correctly in Asterisk using
+`active_mailbox --sort`:
+
+    active_mailbox --sort 15183332225
+
+Messages are renamed in INBOX after sorting
+
+    tree 518/15183332225/INBOX
+        518/15183332225/INBOX
+        |-- msg0000.txt
+        |-- msg0000.wav
+        |-- msg0001.txt
+        |-- msg0001.wav
+        |-- msg0002.txt
+        |-- msg0002.wav
+        |-- msg0003.txt
+        `-- msg0003.wav
+
+
+## Library Usage
+
+ActiveMailbox can also be used in ruby scripts to work with mailboxes
+and voicemail messages.
+
+
+### Working with mailboxes
+
+    # Create a mailbox object
+    mailbox = ActiveMailbox::Mailbox.find('office_a', '1234')
+
+    # Destroy mailbox and all messages/greetings
+    mailbox.destroy!
+
+    # Determine the greeting Asterisk will playback
+    mailbox.current_greeting
+
+    # Destroy ``unavail.wav``
+    mailbox.destroy_greeting!
+
+    # Destroy ``temp.wav``
+    mailbox.destroy_temp!
+
+    # A Hash of the mailbox's messages
+    #
+    # Keys are the subdirectory, lowercased, as
+    # a symbol. Eg: INBOX = :inbox, Old = :old
+    #
+    # Values are arrays of Message objects
+    mailbox.folders
+
+    # Fetch array of messages in :inbox
+    inbox = mailbox.folders[:inbox]
+
+    # Or some sugar
+    inbox = mailbox.inbox
+
+    # Or :old
+    mailbox.folders[:old]
+    mailbox.old
+
+
+### Working with messages
+
+    # Set mailbox
+    mailbox = ActiveMailbox::Mailbox.find('office_a', '1234')
+
+    # Get first message in INBOX
+    vm = mailbox.inbox.first
+
+    # Path to Asterisk generated msg####.txt
+    vm.txt
+
+    # Path to Asterisk generated msg####.wav
+    vm.wav
+
+    # Caller ID name
+    vm.callerid_name
+
+    # Caller ID number
+    vm.callerid_number
+
+    # Message duration (in seconds)
+    vm.duration
+
+    # Delete this message
+    # Deletes wav, txt, mp3, xml files
+    vm.destroy!
+
+
+## Notes
+
+If Asterisk does **not** keep voicemail in
+`/var/spool/asterisk/voicemail` on this server, add the following
+to `~/.bashrc` (or the appropriate shell config file):
+
+    export ASTERISK_VOICEMAIL_ROOT='/my/alternate/voicemail/path'
+
+Note that you can specify this as an ENV variable when running the
+`active_mailbox` executable.
+
+    ASTERISK_VOICEMAIL_ROOT='/root' active_mailbox [OPTION] MAILBOX
+
+
+## Development
+
+ActiveMailbox is still in development, as such, don't use it yet unless you're
+brave. Then again, if you're using Asterisk, you're already a cowboy so have
+fun!
+
+
+## License
+
+MIT License, see LICENSE.

data/Rakefile

@@ -0,0 +1,33 @@
+require 'rake/testtask'
+
+$:.unshift 'lib'
+
+desc "Start an IRB session preloaded with this library"
+task :console do
+  sh "ASTERISK_VOICEMAIL_ROOT='./test/fixtures/' irb -rlib/active_mailbox.rb -I./lib"
+end
+
+require 'sdoc_helpers'
+desc "Push a new version to Gemcutter"
+task :publish do
+  require 'active_mailbox/version'
+
+  ver = ActiveMailbox::Version
+
+  sh "gem build active_mailbox.gemspec"
+  sh "gem push active_mailbox-#{ver}.gem"
+  sh "git tag -a -m 'ActiveMailbox v#{ver}' v#{ver}"
+  sh "git push origin v#{ver}"
+  sh "git push origin master"
+  sh "git clean -fd"
+  sh "rake pages"
+end
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test' << '.'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end

data/bin/active_mailbox

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require 'active_mailbox'
+require 'active_mailbox/cli'
+
+ActiveMailbox::CLI.run!(ARGV)

data/lib/active_mailbox.rb

@@ -0,0 +1,16 @@
+require 'active_mailbox/version'
+require 'active_mailbox/errors'
+require 'active_mailbox/mailbox'
+require 'active_mailbox/folder'
+require 'active_mailbox/message'
+
+module ActiveMailbox
+  # The directory Asterisk records voicemail in
+  #
+  # By default, this is `/var/spool/asterisk/voicemail`. If it isn't,
+  # you did something fancy when building Asterisk. Set
+  # ENV['ASTERISK_VOICEMAIL_ROOT'] to that directory in your library
+  # or add 'export ASTERISK_VOICEMAIL_ROOT="/my/voicemail"' to your
+  # ~/.bashrc
+  VOICEMAIL_ROOT = ENV['ASTERISK_VOICEMAIL_ROOT'] || "/var/spool/asterisk/voicemail"
+end

data/lib/active_mailbox/cli.rb

@@ -0,0 +1,112 @@
+require 'optparse'
+
+module ActiveMailbox
+  #
+  # This class facilites ActiveMailbox's command line functions
+  #
+  class CLI
+
+    #
+    # Invoke the CLI
+    #
+    def self.run!(argv)
+      options = ActiveMailbox::CLI.parse(argv)
+
+      args = [options[:mailbox]]
+      args.unshift(options[:context]) if options[:context]
+
+      mailbox = ActiveMailbox::Mailbox.find(*args)
+
+      if options[:arg]
+        mailbox.send(options[:command], options[:arg])
+      else
+        mailbox.send(options[:command])
+      end
+    end
+
+    #
+    # Parse CLI arguments (ARGV)
+    #
+    def self.parse(argv)
+      options = {}
+
+      ::OptionParser.new do |opts|
+        opts.banner = "Usage: active_mailbox [OPTION] MAILBOX\n"
+
+        opts.separator ""
+        opts.separator "Mailbox Options:"
+
+        opts.on('--context', 'Look for [MAILBOX] in [CONTEXT]') do |context|
+          options[:context] = conext
+        end
+
+        opts.on('--delete', 'Delete [MAILBOX] and all messages') do
+          options[:command] = :delete!
+        end
+
+        opts.on('--sort', 'Sort messages in [MAILBOX] (recursive)') do
+          options[:command] = :sort!
+        end
+
+        opts.separator ""
+        opts.separator "Cleanup Options:"
+
+        opts.on('--clean-ghosts', "Cleanup 'ghost' messages") do
+          options[:command] = :clean_ghosts!
+        end
+
+        opts.on('--clean-stale', 'Cleanup messages older than 30 days') do
+          options[:command] = :clean_stale!
+        end
+
+        opts.on('--clean-mp3s', 'Cleanup [MAILBOX]/.mp3 directory') do
+          options[:command] = :clean_mp3s!
+        end
+
+        opts.on('--purge', 'Remove all messages, but leave [MAILBOX] folders intact') do
+          options[:command] = :purge!
+        end
+
+        opts.separator ""
+        opts.separator "Greeting Options:"
+
+        opts.on('--delete-temp', 'Delete [MAILBOX]/temp.wav') do
+          options[:command] = :delete_temp_greeting!
+        end
+
+        opts.on('--delete-unavail', 'Delete [MAILBOX]/unavail.wav') do
+          options[:command] = :delete_unavail_greeting!
+        end
+
+        opts.on('--delete-busy', 'Delete [MAILBOX]/busy.wav') do
+          options[:command] = :delete_busy_greeting!
+        end
+
+        opts.separator ""
+        opts.separator "General Options:"
+
+        opts.on('-h', '--help', 'Show this message') do
+          options[:command] = :help
+          puts opts
+          exit
+        end
+
+        opts.on('-v', '--version', 'Show version') do
+          options[:command] = :version
+          puts ActiveMailbox::Version
+          exit
+        end
+
+        begin
+          argv = ['-h'] if argv.empty?
+          opts.parse!(argv)
+          options[:mailbox] = argv.shift
+          options
+        rescue ::OptionParser::ParseError => err
+          STDERR.puts err.message, "\n", opts
+          exit(-1)
+        end
+      end
+    end
+  end
+end

data/lib/active_mailbox/errors.rb

@@ -0,0 +1,8 @@
+module ActiveMailbox
+  module Errors #:nodoc: all
+    class MailboxNotFound  < StandardError; end
+    class MessageNotFound  < StandardError; end
+    class FolderNotFound   < StandardError; end
+    class GreetingNotFound < StandardError; end
+  end
+end

data/lib/active_mailbox/folder.rb

@@ -0,0 +1,166 @@
+module ActiveMailbox
+  #
+  # ActiveMailbox::Folder represents an Asterisk mailbox Folder, such as
+  # INBOX, or Old. They contain the actuall messages for a mailbox.
+  #
+  class Folder
+
+    include Comparable
+
+    attr_reader :path, :mailbox
+
+    attr_accessor :reload_messages
+
+    #
+    # Create a new Folder object
+    #
+    def initialize(path, mailbox)
+      unless File.exists?(path)
+        raise ActiveMailbox::Errors::FolderNotFound, "#{path} does not exist"
+      end
+      @mailbox = mailbox
+      @path = path
+    end
+
+    #
+    # Compare base on path
+    #
+    def <=>(other)
+      path <=> other.path
+    end
+
+    #
+    # An array of Message objects in this folder
+    #
+    def messages(reload = false)
+      if reload or @reload_messages or ! defined?(@messages)
+        @messages = []
+        Dir.chdir(@path) do
+          Dir["*.txt"].each do |txt|
+            @messages << Message.new("#{Dir.pwd}/#{txt}", self)
+          end
+        end
+      end
+      @messages
+    ensure
+      @reload_messages = false
+    end
+
+    #
+    # The name of this folder
+    #
+    def name
+      @name ||= path.split('/').last
+    end
+
+    #
+    # Returns number of messages in this folder
+    #
+    def count
+      messages.count
+    end
+    alias :size :count
+
+    #
+    # Sort messages in this folder
+    #
+    # Eg:
+    #   Before Sort: msg0002, msg0005, msg0010, msg0020
+    #   After Sort:  msg0000, msg0001, msg0002, msg0003
+    #
+    def sort!
+      unless messages.size == messages.last.number + 1
+
+        renamer = lambda do |old_file, new_file|
+          %w[wav txt].each do |ext|
+            File.rename("#{old_file}.#{ext}", "#{new_file}.#{ext}")
+          end
+        end
+
+        messages.each_with_index.map do |message, index|
+          old_file = message.path
+          tmp_file = old_file.sub(/msg[0-9]{4}/, 'temp_msg%04d' % index)
+          renamer.call(old_file, tmp_file)
+          [old_file, tmp_file]
+        end.each do |old_file, tmp_file|
+          new_file = tmp_file.sub('temp_msg', 'msg')
+          renamer.call(tmp_file, new_file)
+        end
+      end
+    ensure
+      @reload_messages = true
+    end
+
+    #
+    # Destroy all messages/info files in this folder
+    #
+    def purge!
+      Dir.chdir(@path) do
+        Dir["*"].each do |file|
+          File.unlink(file)
+        end
+      end
+    ensure
+      @reload_messages = true
+    end
+
+    #
+    # Clean all 'ghost' Messages in this Folder
+    #
+    # A 'ghost' voicemail occurs when the .wav file does not exist.
+    # Asterisk sees the info (txt) file and thinks a voicemail exists,
+    # then plays nothing as the wav is not found.
+    #
+    # At the same time, you might run into issues if a wav exists, but
+    # not the txt file.
+    #
+    def clean_ghosts!(autosort = true)
+      Dir.chdir(@path) do
+        message_list.each do |file|
+          txt = "#{Dir.pwd}/#{file}.txt"
+          wav = "#{Dir.pwd}/#{file}.wav"
+
+          txt_exists = File.exists?(txt)
+          wav_exists = File.exists?(wav)
+
+          unless txt_exists && wav_exists
+            File.unlink(txt) if txt_exists
+            File.unlink(wav) if wav_exists
+          end
+        end
+      end
+      sort! if autosort
+    end
+
+    #
+    # Destroy Messages in this Folder that are older than 30 days
+    #
+    def clean_stale!(autosort = true)
+      messages.each do |message|
+        message.destroy! if message.stale?
+      end
+      sort! if autosort
+    end
+
+    #
+    # Destroy this Folder
+    #
+    def destroy!
+      FileUtils.rm_rf(@path)
+    end
+
+  private
+    #
+    # Grabs a list of valid message files in this folder
+    #
+    def message_list(strip_extension = true)
+      Dir['msg[0-9][0-9][0-9][0-9]*'].map do |file|
+        if strip_extension
+          file.split('.').first
+        else
+          file
+        end
+      end.uniq
+    end
+  end
+end