Create 1.0.x-dev branch.

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v1.0
+### Changes
+* Added `$date_from` and `$date_to` params to the `Shop::getLedgerEntries` method. These params expect either a unix timestamp or an instance of DateTime. If left empty or set to false they will default to the past 7 days.
+* Added `linkFile` method to the Listing resource. Removed support for linking a file from the `uploadFile` method.
+* Added `linkImage` method to the Listing resource. Removed support for linking an image from the `uploadImage` method.
+* Added `$file`, `$name` and `$rank` params to the `Listing::uploadFile` method. Removed the `$data` param.
+* Added `$file`, `$name`, `$rank` and `$options` params to the `Listing::uploadImage` method. Removed the `$data` param.
+* Removed the `Listing::updateInventory` method. This has been replaced with `ListingInventory::update`.
+
+### Fixed issues
+* UploadFile request was throwing an exception if 'image' parameter was missing. This check has been removed.
+
 ## v0.3.2
 ### Fixed issues
 * Fixed issue with associated properties being incorrectly updated on create() methods resulting in "Indirect modification of overloaded property" error. [Issue #9](https://github.com/rhysnhall/etsy-php-sdk/issues/9)

README.md

@@ -85,7 +85,7 @@ The final step is to get the access token for the user. To do this you will need
 );
 ```
 
-You'll be provided with both an access token and a refresh token. The access token has a valid duration of 3600 seconds (1 hour). Save both of these for late ruse.
+You'll be provided with both an access token and a refresh token. The access token has a valid duration of 3600 seconds (1 hour). Save both of these for late use.
 
 #### Refreshing your token
 

src/Resources/Listing.php

@@ -125,13 +125,46 @@ public function getFile($listing_file_id) {
    * Uploads a listing file.
    *
    * @link https://developers.etsy.com/documentation/reference#operation/uploadListingFile
-   * @param array $data
+   * @param resource $file
+   * @param string $name
+   * @param integer|string $rank
    * @return Etsy\Resources\ListingFile
    */
-  public function uploadFile(array $data) {
-    if(!isset($data['image']) && !isset($data['listing_image_id'])) {
-      throw new ApiException("Request requires either 'listing_file_id' or 'file' paramater.");
+  public function uploadFile(
+    $file,
+    string $name,
+    $rank = 1
+  ) {
+    $data = [
+      'file' => $file,
+      'name' => $name,
+      'rank' => $rank
+    ];
+    $listing_file = $this->request(
+      "POST",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/files",
+      "ListingFile",
+      $data
+    );
+    if($listing_file) {
+      $listing_file->shop_id = $this->shop_id;
     }
+    return $listing_file;
+  }
+
+  /**
+   * Links an existing file to the Listing.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/uploadListingFile
+   * @param integer|string $listing_file_id
+   * @param integer|string $rank
+   * @return Etsy\Resources\ListingFile
+   */
+  public function linkFile($listing_file_id, $rank = 1) {
+    $data = [
+      'listing_file_id' => $listing_file_id,
+      'rank' => 1
+    ];
     $listing_file = $this->request(
       "POST",
       "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/files",
@@ -182,13 +215,23 @@ public function getImage($listing_image_id) {
    * Upload a listing image.
    *
    * @link https://developers.etsy.com/documentation/reference#operation/uploadListingImage
-   * @param array $data
+   * @param resource $file
+   * @param string $name
+   * @param integer|string $rank
+   * @param array $options
    * @return Etsy\Resources\ListingImage
    */
-  public function uploadImage(array $data) {
-    if(!isset($data['image']) && !isset($data['listing_image_id'])) {
-      throw new ApiException("Request requires either 'listing_image_id' or 'image' paramater.");
-    }
+  public function uploadImage(
+    $file,
+    string $name,
+    $rank = 1,
+    array $options
+  ) {
+    $data = array_merge($options, [
+      'file' => $file,
+      'name' => $name,
+      'rank' => $rank
+    ]);
     $listing_image = $this->request(
       "POST",
       "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/images",
@@ -202,25 +245,33 @@ public function uploadImage(array $data) {
   }
 
   /**
-   * Get the inventory for the listing.
+   * Links an existing image to the Listing.
    *
-   * @link https://developers.etsy.com/documentation/reference#operation/getListingInventory
-   * @return Etsy\Resources\ListingInventory
+   * @link https://developers.etsy.com/documentation/reference#operation/uploadListingImage
+   * @param integer|string $listing_file_id
+   * @param integer|string $rank
+   * @param array $options
    */
-  public function getInventory() {
-    $inventory = $this->request(
-      "GET",
-      "/application/listings/{$this->listing_id}/inventory",
-      "ListingInventory"
-    );
-    // Assign the listing ID to associated inventory products.
-    array_map(
-      (function($product){
-        $product->listing_id = $this->listing_id;
-      }),
-      ($inventory->products ?? [])
+  public function linkImage(
+    $listing_image_id,
+    $rank = 1,
+    array $options = []
+  ) {
+    // Attach the options.
+    $data = array_merge($options, [
+      'listing_image_id' => $listing_image_id,
+      'rank' => $rank
+    ]);
+    $listing_image = $this->request(
+      "POST",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/images",
+      "ListingImage",
+      $data
     );
-    return $inventory;
+    if($listing_image) {
+      $listing_image->shop_id = $this->shop_id;
+    }
+    return $listing_image;
   }
 
   /**

src/Resources/ListingInventory.php

@@ -19,4 +19,27 @@ class ListingInventory extends Resource {
     "products" => "ListingProduct"
   ];
 
+  /**
+   * Update the Listing Inventory record.
+   *
+   * @link https://developers.etsy.com/documentation/reference/#operation/updateListingInventory
+   * @param array $data
+   * @return Etsy\Resources\ListingInventory
+   */
+  public function update() {
+    // Don't use a regular resource update request here.
+    $inventory = $this->updateRequest(
+      "/application/listings/{$this->listing_id}/inventory",
+      $data
+    );
+    // Assign the listing ID to associated inventory products.
+    array_map(
+      (function($product){
+        $product->listing_id = $this->listing_id;
+      }),
+      ($inventory->products ?? [])
+    );
+    return $this;
+  }
+
 }

src/Resources/Shop.php

@@ -3,7 +3,8 @@
 namespace Etsy\Resources;
 
 use Etsy\Resource;
-use Etsy\Exception\ApiException;
+use Etsy\Exception\SdkException;
+use Etsy\Utils\Date;
 
 /**
  * Shop resource class. Represents a Etsy user's shop.
@@ -68,7 +69,7 @@ public function getSection($section_id) {
    */
   public function createSection(string $title) {
     if(!strlen(trim($title))) {
-      throw new ApiException("Section title cannot be blank.");
+      throw new SdkException("Section title cannot be blank.");
     }
     return $this->request(
       "POST",
@@ -244,10 +245,30 @@ public function getTransaction($transaction_id) {
    * Get all payment account ledger entries for the shop.
    *
    * @link https://developers.etsy.com/documentation/reference#tag/Ledger-Entry
+   * @param mixed $date_from
+   * @param mixed $date_to
    * @param array $params
    * @return Etsy\Collection[Etsy\Resources\LedgerEntry]
    */
-  public function getLedgerEntries(array $params = []) {
+  public function getLedgerEntries(
+    $date_from = false,
+    $date_to = false,
+    array $params = []
+  ) {
+    // Default period is 7 days.
+    if(!$date_from && !$date_to) {
+      $date_from = Date::now()->modify('-1 week')->getTimestamp();
+      $date_to = Date::now()->getTimestamp();
+    }
+    if($date_from instanceof \DateTime) {
+      $date_from = $date_from->getTimestamp();
+    }
+    if($date_to instanceof \DateTime) {
+      $date_to = $date_to->getTimestamp();
+    }
+    // We don't validate wether the string is a valid timestamp.
+    $params['min_created'] = $date_from;
+    $params['max_created'] = $date_to;
     return $this->request(
       "GET",
       "/application/shops/{$this->shop_id}/payment-account/ledger-entries",

src/Utils/Date.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Etsy\Utils;
+
+/**
+ *  Date request utilities.
+ *
+ * @author Rhys Hall [email protected]
+ */
+class Date {
+
+  /**
+   * Creates a DateTime object for now.
+   *
+   * @return DateTime
+   */
+  public static function now() {
+    return new \DateTime('now');
+  }
+
+}