README.md in ctm-0.4.4 vs README.md in ctm-0.5.0

@@ -9,117 +9,386 @@
 
 Usage
 -----
 
 ```ruby
-
 require 'ctm'
 
-# get an access token
+# Authentication
+
 access_token = CTM::Auth.authenticate(ENV['CTM_TOKEN'], ENV['CTM_SECRET'])
 
-# see the list of accounts
-puts CTM::Account.list(access_token).inspect
+account = access_token.accounts.first
+number  = account.numbers.first
 
-# use this access token globally, instead of passing it to each method
-CTM::Auth.token = access_token
+# Accounts
 
-# get my first account
-account = CTM::Account.first
+puts "Accounts you have access to (#{access_token.accounts.total_entries}):"
+access_token.accounts.each do|a|
+  puts "  #{a.name} -> #{a.status}, #{a.balance}"
+end
 
-# get an account by name
-account = CTM::Account.find("name" => "My Account Name")
+puts
+puts "Select an account:"
+account = access_token.accounts.first
+puts "  First account: #{account.name}"
 
-# get a list of numbers within this account, returns 10 at a time by default
+account = access_token.accounts.find('name' => 'CallTrackingMetrics').first
+puts "  Found by name: #{account.name}"
+
+# Tracking Numbers
+
+puts
 numbers = account.numbers
-puts numbers.first.inspect
-puts numbers.total_entries.inspect
-puts numbers.page.inspect
-puts numbers.per_page.inspect
-numbers.each {|number|
-  puts number.id
-  puts "#{number.name} #{number.number} -> #{number.formatted}"
-}
+puts "Tracking Numbers within the Account (#{numbers.total_entries}):"
 
-# get the next 20 numbers on page 2
-numbers = account.numbers(:page => 2, :per_page => 20)
+puts "  Page %-67s %-14s Formatted" % ["ID", "Number"]
+numbers.each_with_index do|n, i|
+  break if i > 4
+  puts "  %-4d %s %-14s %s" % [numbers.page, n.id, n.number, n.formatted]
+end
 
-# search for new numbers to purchase
-numbers = account.numbers.search("+1", :areacode => "410")
-numbers = account.numbers.search("+1", :tollfree => true, :areacode => "888")
-numbers = account.number.search("+44", :contains => "55")
+puts '  ...'
 
-# purchase a new number
-number = account.numbers.buy(numbers.first.digits)
-if number.purchased?
-  puts "successfully purchased the number: #{number.digits_formated}"
-else
-  puts "failed to purchase that number"
+numbers.page = numbers.total_pages
+numbers.entries.reverse.each_with_index do|n, i|
+  break if i > 4
+  puts "  %-4d %s %-14s %s" % [numbers.page, n.id, n.number, n.formatted]
 end
 
-# release the number, removing it from the account
-number.release!
+puts
+puts "Modify routing preferences"
+[:round_robin, :least_connected, :simultaneous].each do |routing|
+  number.routing = routing
+  puts "  #{number.formatted} currently uses #{number.routing} routing"
+end
 
-# create a source from a predefined source
-source = account.sources.create(predefined: 'google_adwords')
+# Receiving Numbers
 
-# list predefined sources
-predefined = account.predefined
+numbers = account.receiving_numbers
+puts
+puts "Receiving Numbers within the Account (#{numbers.total_entries}):"
 
-# customize a source
-source = account.sources.find(:name => "Google Adwords")
-source.landing_url = "utm_campaign=MyCampaign"
-source.save
+puts "  Page %-67s %-14s Formatted" % ["ID", "Number"]
+numbers.each_with_index do|n, i|
+  break if i > 4
+  puts "  %-4d %s %-14s %s" % [numbers.page, n.id, n.number, n.formatted]
+end
 
-# assign a source to a number
-source.numbers.add(number)
+puts '  ...'
 
-# get a list of receiving numbers
-receiving_numbers = account.receiving_numbers
+numbers.page = numbers.total_pages
+numbers.entries.reverse.each_with_index do|n, i|
+  break if i > 4
+  puts "  %-4d %s %-14s %s" % [numbers.page, n.id, n.number, n.formatted]
+end
 
-# add a receiving number, note +1 country code is required
-receiving_number = account.receiving_numbers.create(name: "my number", number:"[phone]")
+receiving_number = account.receiving_numbers.create(
+  name: 'demo number', number: '[phone]'
+)
 
-# assign a receiving number to the tracking number
-number.receiving_numbers.add(receiving_number)
-# get the list of receiving numbers for this number
-puts number.receiving_numbers.inspect
-number.save
+puts
+puts "Adding #{receiving_number.formatted}"
+number.receiving_numbers.add receiving_number
 
-# modify the routing preference for the number
-number.routing = :simultaneous # :round_robin, :least_connected
-number.save
+puts "Receiving Numbers for #{number.formatted}"
+number.receiving_numbers.each_page do |page|
+  page.each.map {|n| puts "  #{n.formatted}"}
+end
 
-# add a new user to the account
-account.users.create(first_name: 'First', last_name: 'Last', email: '[e-mail]', notify: true)
+puts
+puts "Removing #{receiving_number.formatted}"
+number.receiving_numbers.rem receiving_number
 
-# list the users
+puts "Receiving Numbers for #{number.formatted}"
+number.receiving_numbers.each_page do |page|
+  page.each {|n| puts "  #{n.formatted}"}
+end
+
+puts "Releasing #{number.formatted}"
+receiving_number.release!
+
+# Purchasing Numbers
+
+puts
+puts "Search for numbers to buy:"
+
+puts "  Country Region PostalCode TollFree Number"
+matches = account.numbers.search("US", searchby: 'tollfree')
+
+total_tollfree = matches.total_entries
+
+matches.each_with_index do |n, i|
+  break if i > 10
+  puts "  %-7s %-6s %-10s %-8s %s" % [n.iso_country,
+                                      n.region, n.postal_code,
+                                      'Yes', n.friendly_name]
+end
+puts '  ...'
+
+matches = account.numbers.search("US",
+  region: 'SC',
+  areacode: 910,
+  pattern: '802'
+)
+
+total_local = matches.total_entries
+
+matches.each_with_index do |n,i|
+  break if i > 10
+  puts "  %-7s %-6s %-10s %-8s %s" % [n.iso_country,
+                                  n.region, n.postal_code,
+                                  'No', n.friendly_name]
+end
+puts '  ...'
+
+puts
+puts "Found #{total_local} local numbers."
+puts "Found #{total_tollfree} toll-free numbers."
+
+puts
+puts "Purchase a number"
+begin
+  number = account.numbers.buy matches.first.phone_number
+  puts "Successfully purchased the number: #{number.number}"
+
+  similar_numbers = account.numbers('number' => number.number)
+  puts "  Search for active numbers matching %s gives %d results:" % [
+    number.number, similar_numbers.total_entries
+  ]
+  similar_numbers.each_page do |p| p.each {|n| puts "    #{n.number}" }
+  end
+
+  number.release!
+  puts "Released number: #{number.number}"
+
+  similar_numbers = account.numbers('number' => number.number)
+  puts "  Search for active numbers matching %s gives %d results:" % [
+    number.number, similar_numbers.total_entries
+  ]
+  similar_numbers.each_page do |p| p.each {|n| puts "    #{n.number}" }
+  end
+
+rescue CTM::Error::Buy => e
+  puts "Failed to purchase number (#{number.number}): #{e.message}"
+end
+
+# Tracking Sources
+
+sources = account.sources
+
+puts
+puts "Tracking Sources within the Account (#{sources.total_entries})"
+puts "  Page %-5s %-30s Referring URL -> Landing URL" % ["ID","Name"]
+1.upto(sources.total_pages) do |page|
+  sources.page = page
+  sources.each do|source|
+    puts "  %-4d %-5d %-30s '%s' -> '%s'" % [
+      sources.page, source.id,
+      source.name,
+      source.referring_url, source.landing_url]
+  end
+end
+
+src = account.sources.find(name: 'Direct').first
+id  = src.id
+
+puts
+puts "Customizing a source #{sources.filters.inspect}"
+
+puts "  Step   %-5s %-30s Referring URL -> Landing URL" % ["ID","Name"]
+puts "  Find   %-5d %-30s '%s' -> '%s'" % [src.id, src.name, src.referring_url, src.landing_url]
+
+src.landing_url   = "utm_campaign=DemoCampain"
+src.referring_url = "some_search_engine.com"
+src.name          = "Demo Source"
+puts "  Change %-5d %-30s '%s' -> '%s'" % [src.id, src.name, src.referring_url, src.landing_url]
+
+src.save
+src = sources.get(id)
+puts "  Save   %-5d %-30s '%s' -> '%s'" % [src.id, src.name, src.referring_url, src.landing_url]
+
+src.landing_url   = ""
+src.referring_url = ""
+src.name          = "Direct"
+src.save
+
+puts "  Revert %-5d %-30s '%s' -> '%s'" % [src.id, src.name, src.referring_url, src.landing_url]
+
+# Users
+
 users = account.users
 
-# create a webhook to send call data at the start of the call
-account.webhooks.create(weburl: "http://myhost.com/new_calls", position: 'start')
+puts
+puts "Creating User with email: [e-mail]"
+jbravo = users.create(
+  first_name: 'Johnny',
+  last_name: 'Bravo',
+  email: '[e-mail]',
+  role: 'admin',
+  notify: false
+).id
 
-# create a webhook to send call data at the end of the call
-account.webhooks.create(weburl: "http://myhost.com/new_calls", position: 'end')
+puts
+puts "Users within the Account (#{users.total_entries})"
+puts "  %-40s %-20s %-20s %s" % %w(ID Name Role Email)
 
-# list webhooks
-account.webhooks
+users.each_page do |page|
+  page.each do|user|
+    puts "  %-40s %-20s %-20s %s" % [user.id, user.name, user.role, user.email]
+  end
+end
 
-# calls - list the calls
-account.calls
+puts
+puts "Removing User: %s" % [ account.users.get(jbravo).release!['status'] ]
 
+# Webhooks
+
+ids = []
+
+puts
+puts "Creating webhook at start and end"
+ids << account.webhooks.create(
+  weburl: "http://example.com/new_call/start",
+  position: 'start'
+).id
+
+ids << account.webhooks.create(
+  weburl: "http://example.com/new_call/end",
+  position: 'end'
+).id
+
+puts "Webhooks in account (#{account.webhooks.total_entries}):"
+puts "  %-5s Position WebURL" % ["ID"]
+account.webhooks.each_page do |page|
+  page.each do |hook|
+    puts "  %-5s %-8s %s" % [hook.id, hook.position, hook.weburl]
+  end
+end
+
+puts "Releasing webhooks"
+ids.each do |i|
+  res = account.webhooks.get(i).release!
+
+  puts "  %s: %s" % [ i, res['status'] == 'deleted' ? res['status'] : res.inspect ]
+end
+
+# Calls
+
 call = account.calls.first
+call_fmt_str = "  %-8s %-20s %-15s %-10s %-10s %-20s %-12s %-20s %-20s %s"
 
-call.notes = "some notes to attach to the call"
+puts
+puts "Call Information:"
+
+puts call_fmt_str % %w(ID Source Likelihood TalkTime RingTime CalledAt DialStatus CallerNumber CallerName Notes)
+puts call_fmt_str % [
+  call.id,
+  call.source,                               call.likelihood,
+  call.talk_time,                            call.ring_time,
+  call.called_at.split(' ')[0..1].join(' '), call.dial_status,
+  call.caller_number_format,                 call.name,
+  call.notes
+]
+
+puts
+puts "Adding note to call:"
+old_note = call.notes
+id = call.id
+call.notes = "Test Note!"
+
+puts call_fmt_str % %w(ID Source Likelihood TalkTime RingTime CalledAt
+DialStatus CallerNumber CallerName Notes)
+puts call_fmt_str % [
+  call.id,
+  call.source,                               call.likelihood,
+  call.talk_time,                            call.ring_time,
+  call.called_at.split(' ')[0..1].join(' '), call.dial_status,
+  call.caller_number_format,                 call.name,
+  call.notes
+]
+
 call.save
 
-# get sale record
-call.sale
+call = account.calls.get id
+puts
+puts "Deleting note from call:"
+puts call_fmt_str % %w(ID Source Likelihood TalkTime RingTime CalledAt
+DialStatus CallerNumber CallerName Notes)
+puts call_fmt_str % [
+  call.id,
+  call.source,                               call.likelihood,
+  call.talk_time,                            call.ring_time,
+  call.called_at.split(' ')[0..1].join(' '), call.dial_status,
+  call.caller_number_format,                 call.name,
+  call.notes
+]
 
-# create sale record, marking the call as a conversion
-call.sale.create(name: "Who", score: 5, conversion: true, value: 34, date: '2013-04-24T00:00:00Z')
-# or update the sale record
-sale = call.sale
-sale.name = "Todd"
-sale.save
+call.notes = old_note
+call.save
+
+# Call Sale Record
+
+old_sale = call.sale
+
+sale_fmt_str = "  %-10s %-10s %-15s %-5s %-5s %-10s"
+
+puts
+puts "Editing Sale on Call #{old_sale.call_id}"
+
+puts sale_fmt_str % ['', *%w(Date CSR Score Value Converted?)]
+puts sale_fmt_str % ['Existing',
+  old_sale.sale_date,
+  old_sale.name,
+  old_sale.score,
+  old_sale.value,
+  old_sale.conversion,
+]
+call.sale.release!
+
+new_sale = call.sale
+puts sale_fmt_str % ['Deleted',
+  new_sale.sale_date,
+  new_sale.name,
+  new_sale.score,
+  new_sale.value,
+  new_sale.conversion,
+]
+
+new_sale = call.sale
+new_sale.name = 'The Doctor'
+new_sale.score = 5
+new_sale.conversion = true
+new_sale.value = 12
+new_sale.sale_date = Date.today.to_s
+
+puts sale_fmt_str % ['Unsaved',
+  new_sale.sale_date,
+  new_sale.name,
+  new_sale.score,
+  new_sale.value,
+  new_sale.conversion,
+]
+
+new_sale.save
+
+new_sale = call.sale
+puts sale_fmt_str % ['Refresh',
+  new_sale.sale_date,
+  new_sale.name,
+  new_sale.score,
+  new_sale.value,
+  new_sale.conversion,
+]
+
+old_sale.save
+new_sale = call.sale
+
+puts sale_fmt_str % ['Restore',
+  new_sale.sale_date,
+  new_sale.name,
+  new_sale.score,
+  new_sale.value,
+  new_sale.conversion,
+]
 
 ```