Add support for the Capability resource and APIs

stripe · May 9, 2019 · 71b2bc0 · 71b2bc0
1 parent 124fafb
commit 71b2bc0
Show file tree

Hide file tree

Showing 6 changed files with 225 additions and 15 deletions.
diff --git a/init.php b/init.php
@@ -67,6 +67,7 @@
 require(dirname(__FILE__) . '/lib/BankAccount.php');
 require(dirname(__FILE__) . '/lib/BitcoinReceiver.php');
 require(dirname(__FILE__) . '/lib/BitcoinTransaction.php');
+require(dirname(__FILE__) . '/lib/Capability.php');
 require(dirname(__FILE__) . '/lib/Card.php');
 require(dirname(__FILE__) . '/lib/Charge.php');
 require(dirname(__FILE__) . '/lib/Checkout/Session.php');

diff --git a/lib/Account.php b/lib/Account.php
@@ -85,6 +85,7 @@ public static function getSavedNestedResources()
         return $savedNestedResources;
     }
 
+    const PATH_CAPABILITIES = '/capabilities';
     const PATH_EXTERNAL_ACCOUNTS = '/external_accounts';
     const PATH_LOGIN_LINKS = '/login_links';
     const PATH_PERSONS = '/persons';
@@ -128,21 +129,6 @@ public function reject($params = null, $opts = null)
         return $this;
     }
 
-    /**
-     * @param array|null $params
-     * @param array|string|null $options
-     *
-     * @return Collection The list of persons.
-     */
-    public function persons($params = null, $options = null)
-    {
-        $url = $this->instanceUrl() . '/persons';
-        list($response, $opts) = $this->_request('get', $url, $params, $options);
-        $obj = Util\Util::convertToStripeObject($response, $opts);
-        $obj->setLastResponse($response);
-        return $obj;
-    }
-
     /**
      * @param array|null $clientId
      * @param array|string|null $opts
@@ -158,6 +144,51 @@ public function deauthorize($clientId = null, $opts = null)
         return OAuth::deauthorize($params, $opts);
     }
 
+    /*
+     * Capabilities methods
+     * We can not add the capabilities() method today as the Account object already has a
+     * capabilities property which is a hash and not the sub-list of capabilities.
+     */
+
+
+    /**
+     * @param string|null $id The ID of the account to which the capability belongs.
+     * @param string|null $capabilityId The ID of the capability to retrieve.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return Capability
+     */
+    public static function retrieveCapability($id, $capabilityId, $params = null, $opts = null)
+    {
+        return self::_retrieveNestedResource($id, static::PATH_CAPABILITIES, $capabilityId, $params, $opts);
+    }
+
+    /**
+     * @param string|null $id The ID of the account to which the capability belongs.
+     * @param string|null $capabilityId The ID of the capability to update.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return Capability
+     */
+    public static function updateCapability($id, $capabilityId, $params = null, $opts = null)
+    {
+        return self::_updateNestedResource($id, static::PATH_CAPABILITIES, $capabilityId, $params, $opts);
+    }
+
+    /**
+     * @param string|null $id The ID of the account on which to retrieve the capabilities.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return Collection The list of capabilities.
+     */
+    public static function allCapabilities($id, $params = null, $opts = null)
+    {
+        return self::_allNestedResources($id, static::PATH_CAPABILITIES, $params, $opts);
+    }
+
     /**
      * @param string|null $id The ID of the account on which to create the external account.
      * @param array|null $params
@@ -233,6 +264,21 @@ public static function createLoginLink($id, $params = null, $opts = null)
         return self::_createNestedResource($id, static::PATH_LOGIN_LINKS, $params, $opts);
     }
 
+    /**
+     * @param array|null $params
+     * @param array|string|null $options
+     *
+     * @return Collection The list of persons.
+     */
+    public function persons($params = null, $options = null)
+    {
+        $url = $this->instanceUrl() . '/persons';
+        list($response, $opts) = $this->_request('get', $url, $params, $options);
+        $obj = Util\Util::convertToStripeObject($response, $opts);
+        $obj->setLastResponse($response);
+        return $obj;
+    }
+
     /**
      * @param string|null $id The ID of the account on which to create the person.
      * @param array|null $params

diff --git a/lib/Capability.php b/lib/Capability.php
@@ -0,0 +1,83 @@
+<?php
+
+namespace Stripe;
+
+/**
+ * Class Capability
+ *
+ * @package Stripe
+ *
+ * @property string $id
+ * @property string $object
+ * @property string $account
+ * @property bool $requested
+ * @property int $requested_at
+ * @property mixed $requirements
+ * @property string $status
+ */
+class Capability extends ApiResource
+{
+
+    const OBJECT_NAME = "capability";
+
+    use ApiOperations\Update;
+
+    /**
+     * Possible string representations of a capability's status.
+     * @link https://stripe.com/docs/api/capabilities/object#capability_object-status
+     */
+    const STATUS_ACTIVE      = 'active';
+    const STATUS_INACTIVE    = 'inactive';
+    const STATUS_PENDING     = 'pending';
+    const STATUS_UNREQUESTED = 'unrequested';
+
+    /**
+     * @return string The API URL for this Stripe account reversal.
+     */
+    public function instanceUrl()
+    {
+        $id = $this['id'];
+        $account = $this['account'];
+        if (!$id) {
+            throw new Error\InvalidRequest(
+                "Could not determine which URL to request: " .
+                "class instance has invalid ID: $id",
+                null
+            );
+        }
+        $id = Util\Util::utf8($id);
+        $account = Util\Util::utf8($account);
+
+        $base = Account::classUrl();
+        $accountExtn = urlencode($account);
+        $extn = urlencode($id);
+        return "$base/$accountExtn/capabilities/$extn";
+    }
+
+    /**
+     * @param array|string $_id
+     * @param array|string|null $_opts
+     *
+     * @throws \Stripe\Error\InvalidRequest
+     */
+    public static function retrieve($_id, $_opts = null)
+    {
+        $msg = "Capabilities cannot be accessed without an account ID. " .
+               "Retrieve a Capability using \$account->retrieveCapability('acap_123') instead.";
+        throw new Error\InvalidRequest($msg, null);
+    }
+
+    /**
+     * @param string $_id
+     * @param array|null $_params
+     * @param array|string|null $_options
+     *
+     * @throws \Stripe\Error\InvalidRequest
+     */
+    public static function update($_id, $_params = null, $_options = null)
+    {
+        $msg = "Capabilities cannot be accessed without an account ID. " .
+               "Update a Capability using \$account->updateCapability('acap_123') instead.";
+        throw new Error\InvalidRequest($msg, null);
+    }
+}
diff --git a/lib/Util/Util.php b/lib/Util/Util.php
@@ -80,6 +80,7 @@ public static function convertToStripeObject($resp, $opts)
             \Stripe\BankAccount::OBJECT_NAME => 'Stripe\\BankAccount',
             \Stripe\BitcoinReceiver::OBJECT_NAME => 'Stripe\\BitcoinReceiver',
             \Stripe\BitcoinTransaction::OBJECT_NAME => 'Stripe\\BitcoinTransaction',
+            \Stripe\Capability::OBJECT_NAME => 'Stripe\\Capability',
             \Stripe\Card::OBJECT_NAME => 'Stripe\\Card',
             \Stripe\Charge::OBJECT_NAME => 'Stripe\\Charge',
             \Stripe\Checkout\Session::OBJECT_NAME => 'Stripe\\Checkout\\Session',

diff --git a/tests/Stripe/AccountTest.php b/tests/Stripe/AccountTest.php
@@ -5,6 +5,7 @@
 class AccountTest extends TestCase
 {
     const TEST_RESOURCE_ID = 'acct_123';
+    const TEST_CAPABILITY_ID = 'acap_123';
     const TEST_EXTERNALACCOUNT_ID = 'ba_123';
     const TEST_PERSON_ID = 'person_123';
 
@@ -129,6 +130,38 @@ public function testPersons()
         $this->assertInstanceOf("Stripe\\Person", $persons->data[0]);
     }
 
+    public function testCanRetrieveCapability()
+    {
+        $this->expectsRequest(
+            'get',
+            '/v1/accounts/' . self::TEST_RESOURCE_ID . '/capabilities/' . self::TEST_CAPABILITY_ID
+        );
+        $resource = Account::retrieveCapability(self::TEST_RESOURCE_ID, self::TEST_CAPABILITY_ID);
+        $this->assertInstanceOf("Stripe\\Capability", $resource);
+    }
+
+    public function testCanUpdateCapability()
+    {
+        $this->expectsRequest(
+            'post',
+            '/v1/accounts/' . self::TEST_RESOURCE_ID . '/capabilities/' . self::TEST_CAPABILITY_ID
+        );
+        $resource = Account::updateCapability(self::TEST_RESOURCE_ID, self::TEST_CAPABILITY_ID, [
+            "requested" => true,
+        ]);
+        $this->assertInstanceOf("Stripe\\Capability", $resource);
+    }
+
+    public function testCanListCapabilities()
+    {
+        $this->expectsRequest(
+            'get',
+            '/v1/accounts/' . self::TEST_RESOURCE_ID . '/capabilities'
+        );
+        $resources = Account::allCapabilities(self::TEST_RESOURCE_ID);
+        $this->assertTrue(is_array($resources->data));
+    }
+
     public function testCanCreateExternalAccount()
     {
         $this->expectsRequest(

diff --git a/tests/Stripe/CapabilityTest.php b/tests/Stripe/CapabilityTest.php
@@ -0,0 +1,46 @@
+<?php
+
+namespace Stripe;
+
+class CapabilityTest extends TestCase
+{
+    const TEST_ACCOUNT_ID = 'acct_123';
+    const TEST_RESOURCE_ID = 'acap_123';
+
+    public function testHasCorrectUrl()
+    {
+        $resource = \Stripe\Account::retrieveCapability(self::TEST_ACCOUNT_ID, self::TEST_RESOURCE_ID);
+        $this->assertSame(
+            "/v1/accounts/" . self::TEST_ACCOUNT_ID . "/capabilities/" . self::TEST_RESOURCE_ID,
+            $resource->instanceUrl()
+        );
+    }
+
+    /**
+     * @expectedException \Stripe\Error\InvalidRequest
+     */
+    public function testIsNotDirectlyRetrievable()
+    {
+        Capability::retrieve(self::TEST_RESOURCE_ID);
+    }
+
+    public function testIsSaveable()
+    {
+        $resource = \Stripe\Account::retrieveCapability(self::TEST_ACCOUNT_ID, self::TEST_RESOURCE_ID);
+        $resource->requested = true;
+        $this->expectsRequest(
+            'post',
+            '/v1/accounts/' . self::TEST_ACCOUNT_ID . '/capabilities/' . self::TEST_RESOURCE_ID
+        );
+        $resource->save();
+        $this->assertSame("Stripe\\Capability", get_class($resource));
+    }
+
+    /**
+     * @expectedException \Stripe\Error\InvalidRequest
+     */
+    public function testIsNotDirectlyUpdatable()
+    {
+        Capability::update(self::TEST_RESOURCE_ID, ["requested" => true]);
+    }
+}