Fix numbers()->purchase() when providing a string

To purchase a number you must provide a number and the associated
country. We previously tried to automate this using `searchAvailable`
but this only searches *owned* numbers.

To purchase without using a number object, you can now call
`numbers()->purchase($number, $country);`

Resolves #100

Author: mheap

README.md

@@ -356,6 +356,29 @@ $application = $client->applications()->update([
 ], '1a20a124-1775-412b-b623-e6985f4aace0');
 ```
 
+### Search available numbers
+
+You can search for numbers available to purchase in a specific country
+
+```php
+$numbers = $client->numbers()->searchAvailable('US');
+```
+
+### Purchase number
+
+To purchase a number, you can pass in a value returned from number search
+
+```
+$numbers = $client->numbers()->searchAvailable('US');
+$client->numbers()->purchase($numbers[0]);
+```
+
+Or you can specify the number and country manually
+
+```php
+$client->numbers()->purchase('14155550100', 'US');
+```
+
 ## Troubleshooting
 
 Some users have issues making requests due to the following error:

src/Conversations/Collection.php

@@ -175,4 +175,4 @@ public function offsetUnset($offset)
     {
         throw new \RuntimeException('can not unset collection properties');
     }
-}
+}

src/Numbers/Client.php

@@ -197,11 +197,14 @@ private function handleNumberSearchResult($response, $number)
         return $numbers;
     }
 
-    public function purchase($number) {
+    public function purchase($number, $country = null) {
         // We cheat here and fetch a number using the API so that we have the country code which is required
         // to make a cancel request
         if (!$number instanceof Number) {
-            $number = $this->get($number);
+            if (!$country) {
+                throw new Exception\Exception("You must supply a country in addition to a number to purchase a number");
+            }
+            $number = new Number($number, $country);
         }
 
         $body = [

test/Conversation/responses/conversation.json

@@ -39,4 +39,4 @@
       "_links": []
     }
   }
-}
+}