Methods for User Followers, Profile and Addresses

src/Exception/SdkException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace Etsy\Exception;
+
+class SdkException extends \Exception {
+
+}

src/Resources/Profile.php

@@ -10,4 +10,26 @@
  * @link https://www.etsy.com/developers/documentation/reference/userprofile
  * @author Rhys Hall hello@rhyshall.com
  */
-class Profile extends Resource {}
+class Profile extends Resource {
+
+  /**
+   * @var array
+   */
+  protected $_associations = [
+    'Country' => 'Country'
+  ];
+
+  /**
+   * Updates the shop section.
+   *
+   * @param array $data
+   * @return Etsy\Resource\Profile
+   */
+  public function update(array $data) {
+    return $this->updateRequest(
+        "/users/{$this->user_id}/profile",
+        $data
+      );
+  }
+
+}

src/Resources/User.php

@@ -3,6 +3,8 @@
 namespace Etsy\Resources;
 
 use Etsy\{Resource, Etsy};
+use Etsy\Utils\Address as AddressUtil;
+use Etsy\Exception\SdkException;
 
 /**
  * User resource class. Represents an Etsy User.
@@ -348,5 +350,125 @@ public function getAuthoredFeedback(array $params = []) {
       );
   }
 
+  /**
+   * Gets all followers for the user.
+   *
+   * @param array $params
+   * @return \Etsy\Collection
+   */
+  public function getFollowers(array $params = []) {
+    $params['includes'] = ['Shops', 'Profile'];
+    return $this->request(
+        "GET",
+        "/users/{$this->user_id}/circles",
+        "User",
+        $params
+      );
+  }
+
+  /**
+   * Get all users this user is following.
+   *
+   * @param array $params
+   * @return \Etsy\Collection
+   */
+  public function getFollowing(array $params = []) {
+    $params['includes'] = ['Shops', 'Profile'];
+    return $this->request(
+        "GET",
+        "/users/{$this->user_id}/connected_users",
+        "User",
+        $params
+      );
+  }
+
+  /**
+   * Follows an Etsy user.
+   * @NOTE Etsy will return a 400 if you already follow the user. This is
+   * terrible use of the 400 HTTP code and unfortunately not something I am
+   * adding a work around for. Check if the user is already followed before
+   * making this call.
+   *
+   * @param integer/string $target_user_id
+   * @return \Etsy\Resources\User
+   */
+  public function followUser($target_user_id) {
+    return $this->request(
+        "POST",
+        "/users/{$this->user_id}/connected_users",
+        "User",
+        ['to_user_id' => $target_user_id, 'includes' => ['Shops', 'Profile']]
+      )
+      ->first();
+  }
+
+  /**
+  * @NOTE Etsy will return a 400 if you are not following the user. This is
+  * terrible use of the 400 HTTP code and unfortunately not something I am
+  * adding a work around for. Check if the user is currently followed before
+  * making this call.
+   *
+   * @param integer/string $target_user_id
+   * @return boolean
+   */
+  public function unfollowUser($target_user_id) {
+    return $this->deleteRequest(
+      "/users/{$this->user_id}/circles/{$target_user_id}"
+    );
+  }
+
+  /**
+   * Get all addresses for this user.
+   *
+   * @param array $params
+   * @return \Etsy\Collection
+   */
+  public function getAddresses(array $params = []) {
+    return $this->request(
+        "GET",
+        "/users/{$this->user_id}/addresses",
+        "UserAddress",
+        $params
+      );
+  }
+
+  /**
+   * Gets a single address for this user.
+   *
+   * @param integer/string $address_id
+   * @return \Etsy\Resources\UserAddress
+   */
+  public function getAddress($address_id) {
+    return $this->request(
+        "GET",
+        "/users/{$this->user_id}/addresses/{$address_id}",
+        "UserAddress"
+      )
+      ->first();
+  }
+
+  /**
+   * Creates a new user address.
+   *
+   * @param array $data
+   * @return \Etsy\Resources\UserAddress
+   */
+  public function createUserAddress(array $data) {
+    /**
+     * The Etsy API documentation specifically states that if the country is US, Canada, or Australia then the state value must be a valid abbreviation. It appears that they do not enforce this though and allow you to create a new address with any value in the state field. The below check will ensure the state field is correct. The API will return an error if the state is absent and so we won't validate the states existence. 
+     */
+    if(isset($data['country_id']) && in_array($data['country_id'], array_keys(AddressUtil::VALID_STATES))) {
+      if(isset($data['state'])) {
+        AddressUtil::validateState($data['country_id'], $data['state']);
+      }
+    }
+    return $this->request(
+        "POST",
+        "/users/{$this->user_id}/addresses",
+        "userAddress",
+        $data
+      )
+      ->first();
+  }
 
 }

src/Resources/UserAddress.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Etsy\Resources;
+
+use Etsy\Resource;
+
+/**
+ * UserAddress resource class. Represents a User's profile Address in Etsy.
+ *
+ * @link https://www.etsy.com/developers/documentation/reference/useraddress
+ * @author Rhys Hall hello@rhyshall.com
+ */
+class UserAddress extends Resource {
+
+  /**
+   * @var array
+   */
+  protected $_associations = [
+    'Country' => 'Country',
+    'User' => 'User'
+  ];
+
+  /**
+   * Deletes the cart.
+   *
+   * @return boolean
+   */
+  public function delete() {
+    return $this->deleteRequest(
+        "/users/{$this->user_id}/addresses/{$this->user_address_id}"
+      );
+  }
+
+}

src/Utils/Address.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Etsy\Utils;
+
+use Etsy\Exception\SdkException;
+
+/**
+ *  Methods for handling and validating addresses.
+ *
+ * @author Rhys Hall hello@rhyshall.com
+ */
+class Address {
+
+  /**
+   * 61 = Australia
+   * 79 = Canada
+   * 209 = United States
+   */
+  const VALID_STATES = [
+    61 => ['ACT', 'NSW', 'NT', 'QLD', 'SA', 'TAS', 'VIC', 'WA'],
+    79 => ['AB', 'BC', 'MB', 'NB', 'NL', 'NT', 'NS', 'NU', 'ON', 'PE', 'QC', 'SK', 'YT'],
+    209 => ['AL', 'AK', 'AS', 'AZ', 'AR', 'CA', 'CO', 'CT', 'DE', 'DC', 'FM', 'FL', 'GA', 'GU', 'HI', 'ID', 'IL', 'IN', 'IA', 'KS', 'KY', 'LA', 'ME', 'MH', 'MD', 'MA', 'MI', 'MN', 'MS', 'MO', 'MT', 'NE', 'NV', 'NH', 'NJ', 'NM', 'NY', 'NC', 'ND', 'MP', 'OH', 'OK', 'OR', 'PW', 'PA', 'PR', 'RI', 'SC', 'SD', 'TN', 'TX', 'UT', 'VT', 'VI', 'VA', 'WA', 'WV', 'WI', 'WY', 'AA', 'AE', 'AP']
+  ];
+
+  /**
+   * Validates the state value for required countries. Does not return boolean
+   * but throws an error if state is invalid.
+   *
+   * @param integer/string $country_id
+   * @param string $state
+   * @return void
+   */
+  public static function validateState($country_id, string $state) {
+    if(in_array($country_id, array_keys(self::VALID_STATES))) {
+      if(!in_array($state, self::VALID_STATES[$country_id])) {
+        throw new SdkException("{$state} is not a valid state for country ID {$country_id}. Valid values are ".implode(', ', self::VALID_STATES[$country_id]));
+      }
+    }
+  }
+
+}