Document and add tests for Usage Triggers

twilio · Oct 11, 2012 · 3ddbdba · 3ddbdba
1 parent acc9ffa
commit 3ddbdba
Show file tree

Hide file tree

Showing 3 changed files with 205 additions and 0 deletions.
diff --git a/docs/usage/rest/usage-records.rst b/docs/usage/rest/usage-records.rst
@@ -2,6 +2,10 @@
 Usage Records
 =============
 
+Twilio offers a Usage Record API so you can better measure how much you've been
+using Twilio. Here are some examples of how you can use PHP to access the usage
+API.
+
 Retrieve All Usage Records
 ==========================
 

diff --git a/docs/usage/rest/usage-triggers.rst b/docs/usage/rest/usage-triggers.rst
@@ -0,0 +1,92 @@
+==============
+Usage Triggers
+==============
+
+Twilio offers a Usage Trigger API so you can get notifications when your Twilio
+usage exceeds a given level. Here are some examples of how you can
+use PHP to create new usage triggers or modify existing triggers.
+
+Retrieve A Usage Trigger's Properties
+=====================================
+
+If you know the Sid of your usage trigger, retrieving it is easy.
+
+.. code-block:: php
+
+    $client = new Services_Twilio('AC123', '456bef');
+    $usageSid = 'UT123';
+    $usageTrigger = $client->account->usage_triggers->get($usageSid);
+    echo $usageTrigger->category;
+
+Update Properties on a UsageTrigger
+===================================
+
+.. code-block:: php
+
+    $client = new Services_Twilio('AC123', '456bef');
+    $usageSid = 'UT123';
+    $usageTrigger = $client->account->usage_triggers->get($usageSid);
+    $usageTrigger->update(array(
+        'FriendlyName' => 'New usage trigger friendly name',
+        'CallbackUrl'  => 'http://example.com/new-trigger-url',
+    ));
+
+Retrieve All Triggers
+=====================
+
+.. code-block:: php
+
+    $client = new Services_Twilio('AC123', '456bef');
+    foreach ($client->account->usage_triggers as $trigger) {
+        echo "Category: {$trigger->category}\nTriggerValue: {$trigger->trigger_value}\n";
+    }
+
+Filter Trigger List By Category
+===============================
+
+Pass filters to the `getIterator` function to create a filtered list.
+
+.. code-block:: php
+
+    $client = new Services_Twilio('AC123', '456bef');
+    foreach ($client->account->usage_triggers->getIterator(
+        0, 50, array(
+            'Category' => 'sms',
+        )) as $trigger
+    ) {
+        echo "Value: " . $trigger->trigger_value . "\n";
+    }
+
+Create a New Trigger
+====================
+
+Pass a usage category, a value and a callback URL to the `create` method.
+
+.. code-block:: php
+
+    $client = new Services_Twilio('AC123', '456bef');
+    $trigger = $client->account->usage_triggers->create(
+        'totalprice',
+        '250.75',
+        'http://example.com/usage'
+    );
+
+Create a Recurring Trigger
+==========================
+
+To have your trigger reset once every day, month, or year, pass the
+`Recurring` key as part of the params array. A list of optional
+trigger parameters can be found in the `Usage Triggers Documentation
+<http://www.twilio.com/docs/api/rest/usage-triggers#list-post-optional-paramete
+rs>`_.
+
+.. code-block:: php
+
+    $client = new Services_Twilio('AC123', '456bef');
+    $trigger = $client->account->usage_triggers->create(
+        'totalprice',
+        '250.75',
+        'http://example.com/usage',
+        array('Recurring' => 'monthly', 'TriggerBy' => 'price')
+    );
+
diff --git a/tests/ResourcesTest.php b/tests/ResourcesTest.php
@@ -539,3 +539,112 @@ function testTimeSeriesFilters() {
     }
 }
 
+class UsageTriggersTest extends PHPUnit_Framework_TestCase {
+    function testRetrieveTrigger() {
+        $http = m::mock(new Services_Twilio_TinyHttp);
+        $http->shouldReceive('get')->once()
+            ->with('/2010-04-01/Accounts/AC123/Usage/Triggers/UT123.json')
+            ->andReturn(array(200, array('Content-Type' => 'application/json'),
+                json_encode(array(
+                    'sid' => 'UT123',
+                    'date_created' => 'Tue, 09 Oct 2012 19:27:24 +0000',
+                    'recurring' => null,
+                    'usage_category' => 'totalprice',
+                ))
+            ));
+        $client = new Services_Twilio('AC123', '456bef', '2010-04-01', $http);
+        $usageSid = 'UT123';
+        $usageTrigger = $client->account->usage_triggers->get($usageSid);
+        $this->assertSame('totalprice', $usageTrigger->usage_category);
+    }
+
+    protected $formHeaders = array('Content-Type' => 'application/x-www-form-urlencoded');
+
+    function testUpdateTrigger() {
+        $http = m::mock(new Services_Twilio_TinyHttp);
+        $usageSid = 'UT123';
+        $http->shouldReceive('post')->once()
+            ->with('/2010-04-01/Accounts/AC123/Usage/Triggers/UT123.json', 
+                $this->formHeaders, 'FriendlyName=new')
+            ->andReturn(array(200, array('Content-Type' => 'application/json'),
+                json_encode(array(
+                    'friendly_name' => 'new', 
+                    'sid' => 'UT123',
+                    'uri' => '/2010-04-01/Accounts/AC123/Usage/Triggers/UT123.json'
+                ))
+            ));
+        $http->shouldReceive('get')->once()
+            ->with('/2010-04-01/Accounts/AC123/Usage/Triggers/UT123.json')
+            ->andReturn(array(200, array('Content-Type' => 'application/json'),
+                json_encode(array(
+                    'sid' => 'UT123',
+                    'friendly_name' => 'new',
+                ))
+            ));
+        $client = new Services_Twilio('AC123', '456bef', '2010-04-01', $http);
+        $usageTrigger = $client->account->usage_triggers->get($usageSid);
+        $usageTrigger->update(array(
+            'FriendlyName' => 'new',
+        ));
+        $usageTrigger2 = $client->account->usage_triggers->get($usageSid);
+        $this->assertSame('new', $usageTrigger2->friendly_name);
+    }
+
+    function filterTriggerList() {
+        $http = m::mock(new Services_Twilio_TinyHttp);
+        $params = 'UsageCategory=sms&Page=0&PageSize=50';
+        $http->shouldReceive('get')->once()
+            ->with('/2010-04-01/Accounts/AC123/Usage/Triggers.json?' . $params)
+            ->andReturn(array(200, array('Content-Type' => 'application/json'),
+                json_encode(array('usage_triggers' => array(
+                    array(
+                        'usage_category' => 'sms',
+                        'current_value' => '4',
+                        'trigger_value' => '100.30',
+                    ),
+                    array(
+                        'usage_category' => 'sms',
+                        'current_value' => '4',
+                        'trigger_value' => '400.30',
+                    )),
+                    'next_page_uri' => '/2010-04-01/Accounts/AC123/Usage/Triggers.json?Category=sms&Page=1&PageSize=50',
+                ))
+            ));
+        $params = 'Page=1&PageSize=50&StartDate=2012-08-01&EndDate=2012-08-31&Category=recordings';
+        $http->shouldReceive('get')->once()
+            ->with('/2010-04-01/Accounts/AC123/Usage/Records/Daily.json?' . $params)
+            ->andReturn(array(400, array('Content-Type' => 'application/json'),
+                '{"status":400,"message":"foo", "code": "20006"}'
+            ));
+        $client = new Services_Twilio('AC123', '456bef', '2010-04-01', $http);
+        foreach ($client->account->usage_triggers->getIterator(
+            0, 50, array(
+                'Category' => 'sms',
+            )) as $trigger
+        ) {
+            echo "Value: " . $trigger->trigger_value . "\n";
+        }
+    }
+
+    function testCreateTrigger() {
+        $http = m::mock(new Services_Twilio_TinyHttp);
+        $params = 'UsageCategory=sms&TriggerValue=100&CallbackUrl=foo';
+        $http->shouldReceive('post')->once()
+            ->with('/2010-04-01/Accounts/AC123/Usage/Triggers.json', 
+                $this->formHeaders, $params)
+            ->andReturn(array(201, array('Content-Type' => 'application/json'),
+                json_encode(array(
+                    'usage_category' => 'sms',
+                    'sid' => 'UT123',
+                    'uri' => '/2010-04-01/Accounts/AC123/Usage/Triggers/UT123.json'
+                ))
+            ));
+        $client = new Services_Twilio('AC123', '456bef', '2010-04-01', $http);
+        $trigger = $client->account->usage_triggers->create(
+            'sms',
+            '100',
+            'foo'
+        );
+        $this->assertSame('sms', $trigger->usage_category);
+    }
+}