Release: v6.0.0

- Added support for the new Composite Recommendation endpoint
- Added new parameter `autoPresented` for Detail View and View Portion interactions
- Added new parameter `timeSpent` for View Portion interactions
- Added support for `reqlExpressions` on recommended items

Author: OndraFiedler

README.md

@@ -34,7 +34,7 @@
 Add the dependency into your `build.gradle.kts`:
 
 ```kotlin
-implementation("com.recombee:apiclientkotlin:5.0.0")
+implementation("com.recombee:apiclientkotlin:6.0.0")
 ```
 
 ### 📚 Version Catalogs
@@ -43,7 +43,7 @@ If you're using [version catalogs](https://developer.android.com/build/migrate-t
 
 ```toml
 [versions]
-recombee = "5.0.0"
+recombee = "6.0.0"
 
 [libraries]
 recombee = { group = "com.recombee", name = "apiclientkotlin", version.ref = "recombee" }

build.gradle.kts

@@ -18,7 +18,7 @@ plugins {
 }
 
 group = "com.recombee"
-version = "5.0.0"
+version = "6.0.0"
 
 repositories {
     mavenCentral()

gradle.properties

@@ -1 +1,3 @@
 kotlin.code.style=official
+ossrhUsername=
+ossrhPassword=

src/main/kotlin/com/recombee/apiclientkotlin/RecombeeClient.kt

@@ -165,7 +165,7 @@ public class RecombeeClient(
         return OkHttp3Request.Builder()
             .url(processRequestUri(request))
             .post(createJsonRequestBody(request.bodyParameters))
-            .header("User-Agent", "recombee-kotlin-api-client/5.0.0")
+            .header("User-Agent", "recombee-kotlin-api-client/6.0.0")
             .build()
     }
 

src/main/kotlin/com/recombee/apiclientkotlin/bindings/CompositeRecommendationResponse.kt

@@ -0,0 +1,19 @@
+/*
+ This file is auto-generated, do not edit
+*/
+
+package com.recombee.apiclientkotlin.bindings
+/**
+ * CompositeRecommendationResponse
+ * @param recommId Id of the composite recommendation request
+ * @param source Parameters of the source stage
+ * @param recomms Obtained recommendations
+ * @param numberNextRecommsCalls How many times *Recommend Next Items* have been called for this `recommId`
+ */
+public data class CompositeRecommendationResponse(
+    public val recommId: String,
+    public val source: Recommendation,
+    public val recomms: List<Recommendation>,
+    public val numberNextRecommsCalls: Long? = null): RecombeeBinding() {
+}
+

src/main/kotlin/com/recombee/apiclientkotlin/bindings/CompositeRecommendationStageParameters.kt

@@ -0,0 +1,201 @@
+/*
+ This file is auto-generated, do not edit
+*/
+
+package com.recombee.apiclientkotlin.bindings
+/**
+ * CompositeRecommendationStageParameters
+ * @param returnProperties With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user. 
+
+Example response with `returnProperties` set in the `resultSettings`:
+```json
+    {
+      "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed",
+      "source": {
+        "id": "category-sport"
+      },
+      "recomms": [
+        {
+          "id": "article-1024",
+          "values": {
+            "title": "Champions League: Stunning Comeback Secures Final Spot",
+            "categories": ["Sport", "Football"],
+            "author": "Jane Smith",
+            "url": "newsportal.com/articles/champions-league-comeback"
+          }
+        },
+        {
+          "id": "article-2031",
+          "values": {
+            "title": "Top 10 Moments from the Summer Olympics",
+            "categories": ["Sport", "Olympics"],
+            "author": "Mark Johnson",
+            "url": "newsportal.com/articles/olympic-top-moments"
+          }
+        },
+        {
+          "id": "article-3042",
+          "values": {
+            "title": "Rising Stars in Women's Tennis to Watch This Season",
+            "categories": ["Sport", "Tennis"],
+            "author": "Laura Chen",
+            "url": "newsportal.com/articles/womens-tennis-stars"
+          }
+        }
+      ],
+      "numberNextRecommsCalls": 0
+    }
+
+```
+
+ * @param includedProperties Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.
+
+Example response for  `returnProperties=true` and `includedProperties=title,url` set in `resultSettings`:
+```json
+  {
+    "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed",
+    "source": {
+      "id": "category-sport"
+    },
+    "recomms": [
+      {
+        "id": "article-1024",
+        "values": {
+          "title": "Champions League: Stunning Comeback Secures Final Spot",
+          "url": "newsportal.com/articles/champions-league-comeback"
+        }
+      },
+      {
+        "id": "article-2031",
+        "values": {
+          "title": "Top 10 Moments from the Summer Olympics",
+          "url": "newsportal.com/articles/olympic-top-moments"
+        }
+      },
+      {
+        "id": "article-3042",
+        "values": {
+          "title": "Rising Stars in Women's Tennis to Watch This Season",
+          "url": "newsportal.com/articles/womens-tennis-stars"
+        }
+      }
+    ],
+    "numberNextRecommsCalls": 0
+  }
+
+```
+
+ * @param filter Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended entities based on the values of their attributes.
+
+Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).
+
+ * @param booster Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some entities based on the values of their attributes.
+
+Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).
+
+ * @param logic Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
+See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.
+
+The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
+
+Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).
+
+ * @param reqlExpressions Only usable if the stage corresponds to the one of these recommendation endpoints:
+
+- [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)
+- [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)
+- [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)
+- [Recommend Users to Item](https://docs.recombee.com/api#recommend-users-to-item)
+- [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user)
+
+A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item.
+This can be used to compute additional properties of the recommended items that are not stored in the database.
+
+The keys are the names of the expressions, and the values are the actual ReQL expressions.
+
+Example request:
+```json
+{
+  "reqlExpressions": {
+    "isInUsersCity": "context_user[\"city\"] in 'cities'",
+    "distanceToUser": "earth_distance('location', context_user[\"location\"])"
+  }
+}
+```
+
+Example response:
+```json
+{
+  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
+  "source": {
+    "id": "restaurant-123",
+    "reqlEvaluations": {
+      "isInUsersCity": true,
+      "distanceToUser": 3450.5
+    }
+  },
+  "recomms": 
+    [
+      {
+        "id": "restaurant-178",
+        "reqlEvaluations": {
+          "isInUsersCity": true,
+          "distanceToUser": 5200.2
+        }
+      },
+      {
+        "id": "bar-42",
+        "reqlEvaluations": {
+          "isInUsersCity": false,
+          "distanceToUser": 2516.0
+        }
+      }
+    ],
+   "numberNextRecommsCalls": 0
+}
+```
+
+ * @param minRelevance **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints:
+
+- [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)
+- [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)
+- [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)
+
+If the *userId* is provided:  Specifies the threshold of how relevant must the recommended items be to the user.
+
+Possible values one of: `"low"`, `"medium"`, `"high"`.
+
+The default value is `"low"`, meaning that the system attempts to recommend a number of items equal to *count* at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations being appended to reach the full *count*.
+This behavior may be suppressed by using `"medium"` or `"high"` values. In such case, the system only recommends items of at least the requested relevance and may return less than *count* items when there is not enough data to fulfill it.
+
+ * @param rotationRate **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints:
+- [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)
+- [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)
+- [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)
+- [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user)
+
+If the *userId* is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per request in a backward fashion.
+
+You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example, `rotationRate=0.2` for only slight rotation of recommended items.
+
+ * @param rotationTime **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints:
+- [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)
+- [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)
+- [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)
+- [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user)
+
+If the *userId* is provided: Taking *rotationRate* into account, specifies how long it takes for an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
+
+ */
+public class CompositeRecommendationStageParameters(
+    public val returnProperties: Boolean? = null,
+    public val includedProperties: List<String>? = null,
+    public val filter: String? = null,
+    public val booster: String? = null,
+    public val logic: Logic? = null,
+    public val reqlExpressions: Map<String, String>? = null,
+    public val minRelevance: String? = null,
+    public val rotationRate: Double? = null,
+    public val rotationTime: Double? = null): RecombeeBinding() {
+}
+

src/main/kotlin/com/recombee/apiclientkotlin/bindings/Logic.kt

@@ -9,7 +9,7 @@ package com.recombee.apiclientkotlin.bindings
  * @param settings Parameters passed to the logic
  */
 public class Logic(
-    public val name: String,
+    public val name: String? = null,
     public val settings: Map<String, Any>? = null): RecombeeBinding() {
 }
 

src/main/kotlin/com/recombee/apiclientkotlin/bindings/Recommendation.kt

@@ -4,10 +4,12 @@ package com.recombee.apiclientkotlin.bindings
  * Represents a recommended Item / User / Item Segment
  *
  * @property id The identifier of the recommended entity.
+ * @property reqlEvaluations The results of ReQL expressions provided in the request.
  */
 public data class Recommendation(
     public val id: String,
-    private val values: Map<String, Any>? = null
+    private val values: Map<String, Any>? = null,
+    private val reqlEvaluations: Map<String, Any>? = null,
 ) : RecombeeBinding() {
 
     /**
@@ -20,4 +22,15 @@ public data class Recommendation(
     public fun getValues(): Map<String, Any> {
         return values ?: throw IllegalStateException("The request was not meant to return values (use returnProperties parameter)")
     }
+
+    /**
+     * Retrieves the evaluations of reqlExpressions for the recommended entity.
+     *
+     * @return A map of expression names and their evaluations.
+     * @throws IllegalStateException if the recommendation contains no reqlEvaluations
+     *         (this means none were sent in the `reqlExpressions` parameter of the request).
+     */
+    public fun getReqlEvaluations(): Map<String, Any> {
+        return reqlEvaluations ?: throw IllegalStateException("The recommendation contains no ReQL evaluations (reqlExpressions must be provided in the request)")
+    }
 }

src/main/kotlin/com/recombee/apiclientkotlin/requests/AddDetailView.kt

@@ -16,6 +16,7 @@ import com.recombee.apiclientkotlin.bindings.*
  * @param cascadeCreate Sets whether the given user/item should be created if not present in the database.
  * @param recommId If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation.
  * @param additionalData A dictionary of additional data for the interaction.
+ * @param autoPresented Indicates whether the item was automatically presented to the user (e.g., in a swiping feed) or explicitly requested by the user (e.g., by clicking on a link). Defaults to `false`.
  */
 public class AddDetailView (
     public val userId: String,
@@ -24,7 +25,8 @@ public class AddDetailView (
     public val duration: Long? = null,
     public val cascadeCreate: Boolean? = true,
     public val recommId: String? = null,
-    public val additionalData: Map<String, Any>? = null
+    public val additionalData: Map<String, Any>? = null,
+    public val autoPresented: Boolean? = null
 ): Request<String>(3000) {
 
     /**
@@ -57,6 +59,7 @@ public class AddDetailView (
             cascadeCreate?.let { parameters["cascadeCreate"] = it}
             recommId?.let { parameters["recommId"] = it}
             additionalData?.let { parameters["additionalData"] = it}
+            autoPresented?.let { parameters["autoPresented"] = it}
             return parameters
         }