additionalData for interactions, returnAbGroup for recommendation end…

…points

README.md

@@ -17,7 +17,7 @@ or
 ```
 {
     "require": {
-        "recombee/php-api-client": "^2.2.0"
+        "recombee/php-api-client": "^2.3.0"
     }
 }
 ```
@@ -30,7 +30,7 @@ use Recombee\RecommApi\Client;
 use Recombee\RecommApi\Requests as Reqs;
 use Recombee\RecommApi\Exceptions as Ex;
 
-$client = new Client('--my-database-id--', '--my-secret-token--');
+$client = new Client('--my-database-id--', '--db-private-token--');
 
 const NUM = 100;
 const PROBABILITY_PURCHASED = 0.1;
@@ -74,7 +74,7 @@ use Recombee\RecommApi\Exceptions as Ex;
 const NUM = 100;
 const PROBABILITY_PURCHASED = 0.1;
 
-$client = new Client('--my-database-id--', '--my-secret-token--');
+$client = new Client('--my-database-id--', '--db-private-token--');
 $client->send(new Reqs\ResetDatabase()); //Clear everything from the database
 
 /*

src/RecommApi/Client.php

@@ -52,7 +52,7 @@ public function __construct($account, $token, $protocol = 'http', $options= arra
     }
 
     protected function getUserAgent() {
-        $user_agent = 'recombee-php-api-client/2.2.0';
+        $user_agent = 'recombee-php-api-client/2.3.0';
         if (isset($this->options['serviceName']))
             $user_agent .= ' '.($this->options['serviceName']);
         return $user_agent;

src/RecommApi/Requests/AddBookmark.php

@@ -34,6 +34,10 @@ class AddBookmark extends Request {
      * @var string $recomm_id If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation.
      */
     protected $recomm_id;
+    /**
+     * @var  $additional_data A dictionary of additional data for the interaction.
+     */
+    protected $additional_data;
     /**
      * @var array Array containing values of optional parameters
      */
@@ -54,6 +58,9 @@ class AddBookmark extends Request {
      *     - *recommId*
      *         - Type: string
      *         - Description: If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+     *     - *additionalData*
+     *         - Type: 
+     *         - Description: A dictionary of additional data for the interaction.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
     public function __construct($user_id, $item_id, $optional = array()) {
@@ -62,9 +69,10 @@ public function __construct($user_id, $item_id, $optional = array()) {
         $this->timestamp = isset($optional['timestamp']) ? $optional['timestamp'] : null;
         $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null;
         $this->recomm_id = isset($optional['recommId']) ? $optional['recommId'] : null;
+        $this->additional_data = isset($optional['additionalData']) ? $optional['additionalData'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('timestamp','cascadeCreate','recommId');
+        $existing_optional = array('timestamp','cascadeCreate','recommId','additionalData');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -112,6 +120,8 @@ public function getBodyParameters() {
              $p['cascadeCreate'] = $this-> optional['cascadeCreate'];
         if (isset($this->optional['recommId']))
              $p['recommId'] = $this-> optional['recommId'];
+        if (isset($this->optional['additionalData']))
+             $p['additionalData'] = $this-> optional['additionalData'];
         return $p;
     }
 

src/RecommApi/Requests/AddCartAddition.php

@@ -42,6 +42,10 @@ class AddCartAddition extends Request {
      * @var string $recomm_id If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation.
      */
     protected $recomm_id;
+    /**
+     * @var  $additional_data A dictionary of additional data for the interaction.
+     */
+    protected $additional_data;
     /**
      * @var array Array containing values of optional parameters
      */
@@ -68,6 +72,9 @@ class AddCartAddition extends Request {
      *     - *recommId*
      *         - Type: string
      *         - Description: If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+     *     - *additionalData*
+     *         - Type: 
+     *         - Description: A dictionary of additional data for the interaction.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
     public function __construct($user_id, $item_id, $optional = array()) {
@@ -78,9 +85,10 @@ public function __construct($user_id, $item_id, $optional = array()) {
         $this->amount = isset($optional['amount']) ? $optional['amount'] : null;
         $this->price = isset($optional['price']) ? $optional['price'] : null;
         $this->recomm_id = isset($optional['recommId']) ? $optional['recommId'] : null;
+        $this->additional_data = isset($optional['additionalData']) ? $optional['additionalData'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('timestamp','cascadeCreate','amount','price','recommId');
+        $existing_optional = array('timestamp','cascadeCreate','amount','price','recommId','additionalData');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -132,6 +140,8 @@ public function getBodyParameters() {
              $p['price'] = $this-> optional['price'];
         if (isset($this->optional['recommId']))
              $p['recommId'] = $this-> optional['recommId'];
+        if (isset($this->optional['additionalData']))
+             $p['additionalData'] = $this-> optional['additionalData'];
         return $p;
     }
 

src/RecommApi/Requests/AddDetailView.php

@@ -38,6 +38,10 @@ class AddDetailView extends Request {
      * @var string $recomm_id If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation.
      */
     protected $recomm_id;
+    /**
+     * @var  $additional_data A dictionary of additional data for the interaction.
+     */
+    protected $additional_data;
     /**
      * @var array Array containing values of optional parameters
      */
@@ -61,6 +65,9 @@ class AddDetailView extends Request {
      *     - *recommId*
      *         - Type: string
      *         - Description: If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+     *     - *additionalData*
+     *         - Type: 
+     *         - Description: A dictionary of additional data for the interaction.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
     public function __construct($user_id, $item_id, $optional = array()) {
@@ -70,9 +77,10 @@ public function __construct($user_id, $item_id, $optional = array()) {
         $this->duration = isset($optional['duration']) ? $optional['duration'] : null;
         $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null;
         $this->recomm_id = isset($optional['recommId']) ? $optional['recommId'] : null;
+        $this->additional_data = isset($optional['additionalData']) ? $optional['additionalData'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('timestamp','duration','cascadeCreate','recommId');
+        $existing_optional = array('timestamp','duration','cascadeCreate','recommId','additionalData');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -122,6 +130,8 @@ public function getBodyParameters() {
              $p['cascadeCreate'] = $this-> optional['cascadeCreate'];
         if (isset($this->optional['recommId']))
              $p['recommId'] = $this-> optional['recommId'];
+        if (isset($this->optional['additionalData']))
+             $p['additionalData'] = $this-> optional['additionalData'];
         return $p;
     }
 

src/RecommApi/Requests/AddPurchase.php

@@ -46,6 +46,10 @@ class AddPurchase extends Request {
      * @var string $recomm_id If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation.
      */
     protected $recomm_id;
+    /**
+     * @var  $additional_data A dictionary of additional data for the interaction.
+     */
+    protected $additional_data;
     /**
      * @var array Array containing values of optional parameters
      */
@@ -75,6 +79,9 @@ class AddPurchase extends Request {
      *     - *recommId*
      *         - Type: string
      *         - Description: If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+     *     - *additionalData*
+     *         - Type: 
+     *         - Description: A dictionary of additional data for the interaction.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
     public function __construct($user_id, $item_id, $optional = array()) {
@@ -86,9 +93,10 @@ public function __construct($user_id, $item_id, $optional = array()) {
         $this->price = isset($optional['price']) ? $optional['price'] : null;
         $this->profit = isset($optional['profit']) ? $optional['profit'] : null;
         $this->recomm_id = isset($optional['recommId']) ? $optional['recommId'] : null;
+        $this->additional_data = isset($optional['additionalData']) ? $optional['additionalData'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('timestamp','cascadeCreate','amount','price','profit','recommId');
+        $existing_optional = array('timestamp','cascadeCreate','amount','price','profit','recommId','additionalData');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -142,6 +150,8 @@ public function getBodyParameters() {
              $p['profit'] = $this-> optional['profit'];
         if (isset($this->optional['recommId']))
              $p['recommId'] = $this-> optional['recommId'];
+        if (isset($this->optional['additionalData']))
+             $p['additionalData'] = $this-> optional['additionalData'];
         return $p;
     }
 

src/RecommApi/Requests/AddRating.php

@@ -38,6 +38,10 @@ class AddRating extends Request {
      * @var string $recomm_id If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation.
      */
     protected $recomm_id;
+    /**
+     * @var  $additional_data A dictionary of additional data for the interaction.
+     */
+    protected $additional_data;
     /**
      * @var array Array containing values of optional parameters
      */
@@ -59,6 +63,9 @@ class AddRating extends Request {
      *     - *recommId*
      *         - Type: string
      *         - Description: If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+     *     - *additionalData*
+     *         - Type: 
+     *         - Description: A dictionary of additional data for the interaction.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
     public function __construct($user_id, $item_id, $rating, $optional = array()) {
@@ -68,9 +75,10 @@ public function __construct($user_id, $item_id, $rating, $optional = array()) {
         $this->timestamp = isset($optional['timestamp']) ? $optional['timestamp'] : null;
         $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null;
         $this->recomm_id = isset($optional['recommId']) ? $optional['recommId'] : null;
+        $this->additional_data = isset($optional['additionalData']) ? $optional['additionalData'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('timestamp','cascadeCreate','recommId');
+        $existing_optional = array('timestamp','cascadeCreate','recommId','additionalData');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -119,6 +127,8 @@ public function getBodyParameters() {
              $p['cascadeCreate'] = $this-> optional['cascadeCreate'];
         if (isset($this->optional['recommId']))
              $p['recommId'] = $this-> optional['recommId'];
+        if (isset($this->optional['additionalData']))
+             $p['additionalData'] = $this-> optional['additionalData'];
         return $p;
     }
 

src/RecommApi/Requests/RecommendItemsToItem.php

@@ -12,6 +12,7 @@
 /**
  * Recommends set of items that are somehow related to one given item, *X*. Typical scenario  is when user *A* is viewing *X*. Then you may display items to the user that he might be also interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user *A* into account.
  * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
+ * The returned items are sorted by relevancy (first item being the most relevant).
  */
 class RecommendItemsToItem extends Request {
 
@@ -137,6 +138,10 @@ class RecommendItemsToItem extends Request {
      * @var  $expert_settings Dictionary of custom options.
      */
     protected $expert_settings;
+    /**
+     * @var bool $return_ab_group If there is a custom AB-testing running, return name of group to which the request belongs.
+     */
+    protected $return_ab_group;
     /**
      * @var array Array containing values of optional parameters
      */
@@ -247,6 +252,9 @@ class RecommendItemsToItem extends Request {
      *     - *expertSettings*
      *         - Type: 
      *         - Description: Dictionary of custom options.
+     *     - *returnAbGroup*
+     *         - Type: bool
+     *         - Description: If there is a custom AB-testing running, return name of group to which the request belongs.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
     public function __construct($item_id, $target_user_id, $count, $optional = array()) {
@@ -265,9 +273,10 @@ public function __construct($item_id, $target_user_id, $count, $optional = array
         $this->rotation_rate = isset($optional['rotationRate']) ? $optional['rotationRate'] : null;
         $this->rotation_time = isset($optional['rotationTime']) ? $optional['rotationTime'] : null;
         $this->expert_settings = isset($optional['expertSettings']) ? $optional['expertSettings'] : null;
+        $this->return_ab_group = isset($optional['returnAbGroup']) ? $optional['returnAbGroup'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('userImpact','filter','booster','cascadeCreate','scenario','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime','expertSettings');
+        $existing_optional = array('userImpact','filter','booster','cascadeCreate','scenario','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime','expertSettings','returnAbGroup');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -333,6 +342,8 @@ public function getBodyParameters() {
              $p['rotationTime'] = $this-> optional['rotationTime'];
         if (isset($this->optional['expertSettings']))
              $p['expertSettings'] = $this-> optional['expertSettings'];
+        if (isset($this->optional['returnAbGroup']))
+             $p['returnAbGroup'] = $this-> optional['returnAbGroup'];
         return $p;
     }
 

src/RecommApi/Requests/RecommendItemsToUser.php

@@ -12,6 +12,7 @@
 /**
  * Based on user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for a given user.
  * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
+ * The returned items are sorted by relevancy (first item being the most relevant).
  */
 class RecommendItemsToUser extends Request {
 
@@ -117,6 +118,10 @@ class RecommendItemsToUser extends Request {
      * @var  $expert_settings Dictionary of custom options.
      */
     protected $expert_settings;
+    /**
+     * @var bool $return_ab_group If there is a custom AB-testing running, return name of group to which the request belongs.
+     */
+    protected $return_ab_group;
     /**
      * @var array Array containing values of optional parameters
      */
@@ -211,6 +216,9 @@ class RecommendItemsToUser extends Request {
      *     - *expertSettings*
      *         - Type: 
      *         - Description: Dictionary of custom options.
+     *     - *returnAbGroup*
+     *         - Type: bool
+     *         - Description: If there is a custom AB-testing running, return name of group to which the request belongs.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
     public function __construct($user_id, $count, $optional = array()) {
@@ -227,9 +235,10 @@ public function __construct($user_id, $count, $optional = array()) {
         $this->rotation_rate = isset($optional['rotationRate']) ? $optional['rotationRate'] : null;
         $this->rotation_time = isset($optional['rotationTime']) ? $optional['rotationTime'] : null;
         $this->expert_settings = isset($optional['expertSettings']) ? $optional['expertSettings'] : null;
+        $this->return_ab_group = isset($optional['returnAbGroup']) ? $optional['returnAbGroup'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('filter','booster','cascadeCreate','scenario','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime','expertSettings');
+        $existing_optional = array('filter','booster','cascadeCreate','scenario','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime','expertSettings','returnAbGroup');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -292,6 +301,8 @@ public function getBodyParameters() {
              $p['rotationTime'] = $this-> optional['rotationTime'];
         if (isset($this->optional['expertSettings']))
              $p['expertSettings'] = $this-> optional['expertSettings'];
+        if (isset($this->optional['returnAbGroup']))
+             $p['returnAbGroup'] = $this-> optional['returnAbGroup'];
         return $p;
     }