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

@@ -46,7 +46,7 @@ https://github.com/recombee/swift-api-client
 Alternatively, in `Package.swift`:
 
 ```swift
-.package(url: "https://github.com/recombee/swift-api-client", from: "5.0.2")
+.package(url: "https://github.com/recombee/swift-api-client", from: "6.0.0")
 ```
 
 Then add to your target dependencies:

Sources/RecombeeClient/Bindings/CompositeRecommendationResponse.swift

@@ -0,0 +1,51 @@
+/*
+ This file is auto-generated
+ */
+
+/// CompositeRecommendationResponse Binding
+public struct CompositeRecommendationResponse: RecombeeBinding, Encodable {
+    public typealias CodingKeys = CompositeRecommendationResponseCodingKeys
+
+    /// Id of the composite recommendation request
+    public let recommId: String
+
+    /// Parameters of the source stage
+    public let source: Recommendation
+
+    /// Obtained recommendations
+    public let recomms: [Recommendation]
+
+    /// How many times *Recommend Next Items* have been called for this `recommId`
+    public var numberNextRecommsCalls: Int?
+
+    /// Coding keys for decoding/encoding
+    public enum CompositeRecommendationResponseCodingKeys: String, CodingKey {
+        case recommId
+        case source
+        case recomms
+        case numberNextRecommsCalls
+    }
+
+    /// Initializes CompositeRecommendationResponse Binding
+    /// - Parameters:
+    ///   - recommId: Id of the composite recommendation request
+    ///   - source: Parameters of the source stage
+    ///   - recomms: Obtained recommendations
+    ///   - numberNextRecommsCalls: How many times *Recommend Next Items* have been called for this `recommId`
+    public init(recommId: String, source: Recommendation, recomms: [Recommendation], numberNextRecommsCalls: Int? = nil) {
+        self.recommId = recommId
+        self.source = source
+        self.recomms = recomms
+        self.numberNextRecommsCalls = numberNextRecommsCalls
+    }
+
+    /// Initializes a new `CompositeRecommendationResponse` from a decoder
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+
+        recommId = try Self.decodeMandatorySimpleField(container, forKey: .recommId)
+        source = try Self.decodeMandatorySimpleField(container, forKey: .source)
+        recomms = try Self.decodeMandatorySimpleField(container, forKey: .recomms)
+        numberNextRecommsCalls = Self.decodeSimpleField(container, forKey: .numberNextRecommsCalls)
+    }
+}

Sources/RecombeeClient/Bindings/CompositeRecommendationStageParameters.swift

@@ -7,7 +7,7 @@ public struct Logic: RecombeeBinding, Encodable {
     public typealias CodingKeys = LogicCodingKeys
 
     /// Name of the logic that should be used
-    public let name: String
+    public var name: String?
 
     /// Parameters passed to the logic
     public var settings: JSONDictionary?
@@ -22,7 +22,7 @@ public struct Logic: RecombeeBinding, Encodable {
     /// - Parameters:
     ///   - name: Name of the logic that should be used
     ///   - settings: Parameters passed to the logic
-    public init(name: String, settings: JSONDictionary? = nil) {
+    public init(name: String? = nil, settings: JSONDictionary? = nil) {
         self.name = name
         self.settings = settings
     }
@@ -31,7 +31,7 @@ public struct Logic: RecombeeBinding, Encodable {
     public init(from decoder: Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
 
-        name = try Self.decodeMandatorySimpleField(container, forKey: .name)
+        name = Self.decodeSimpleField(container, forKey: .name)
         settings = Self.decodeJSONField(container, forKey: .settings)
     }
 }

Sources/RecombeeClient/Bindings/Logic.swift

@@ -12,19 +12,29 @@ public struct Recommendation: RecombeeBinding, Encodable {
     /// Property values of the recommended item
     public var values: JSONDictionary?
 
+    /// Dictionary of evaluated ReQL expressions specified in the request and calculated for the recommended item.
+    /// The keys are the names of the ReQL expressions, and the values are the results of the evaluations.
+
+    public var reqlEvaluations: JSONDictionary?
+
     /// Coding keys for decoding/encoding
     public enum RecommendationCodingKeys: String, CodingKey {
         case id
         case values
+        case reqlEvaluations
     }
 
     /// Initializes Recommendation Binding
     /// - Parameters:
     ///   - id: Id of the recommended item
     ///   - values: Property values of the recommended item
-    public init(id: String, values: JSONDictionary? = nil) {
+    ///   - reqlEvaluations: Dictionary of evaluated ReQL expressions specified in the request and calculated for the recommended item.
+    /// The keys are the names of the ReQL expressions, and the values are the results of the evaluations.
+
+    public init(id: String, values: JSONDictionary? = nil, reqlEvaluations: JSONDictionary? = nil) {
         self.id = id
         self.values = values
+        self.reqlEvaluations = reqlEvaluations
     }
 
     /// Initializes a new `Recommendation` from a decoder
@@ -33,5 +43,6 @@ public struct Recommendation: RecombeeBinding, Encodable {
 
         id = try Self.decodeMandatorySimpleField(container, forKey: .id)
         values = Self.decodeJSONField(container, forKey: .values)
+        reqlEvaluations = Self.decodeJSONField(container, forKey: .reqlEvaluations)
     }
 }

Sources/RecombeeClient/Bindings/Recommendation.swift

@@ -29,6 +29,9 @@ public struct AddDetailView: Request {
     /// A dictionary of additional data for the interaction.
     public var additionalData: JSONDictionary? = nil
 
+    /// 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 var autoPresented: Bool? = nil
+
     /// Initializes AddDetailView request
     /// - Parameters:
     ///   - userId: User who viewed the item
@@ -38,14 +41,16 @@ public struct AddDetailView: Request {
     ///   - cascadeCreate: Sets whether the given user/item should be created if not present in the database.
     ///   - recommId: If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation.
     ///   - additionalData: A dictionary of additional data for the interaction.
-    public init(userId: String, itemId: String, timestamp: Date? = nil, duration: Int? = nil, cascadeCreate: Bool? = true, recommId: String? = nil, additionalData: JSONDictionary? = nil) {
+    ///   - 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 init(userId: String, itemId: String, timestamp: Date? = nil, duration: Int? = nil, cascadeCreate: Bool? = true, recommId: String? = nil, additionalData: JSONDictionary? = nil, autoPresented: Bool? = nil) {
         self.userId = userId
         self.itemId = itemId
         self.timestamp = timestamp
         self.duration = duration
         self.cascadeCreate = cascadeCreate
         self.recommId = recommId
         self.additionalData = additionalData
+        self.autoPresented = autoPresented
     }
 
     /// The API path for the request
@@ -92,6 +97,10 @@ public struct AddDetailView: Request {
             body["additionalData"] = additionalData
         }
 
+        if let autoPresented = autoPresented {
+            body["autoPresented"] = autoPresented
+        }
+
         return body
     }
 }

Sources/RecombeeClient/Requests/AddDetailView.swift

@@ -0,0 +1,162 @@
+/*
+ This file is auto-generated
+ */
+
+import Foundation
+
+/// Composite Recommendation returns both a *source entity* (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations.html)) and a list of related recommendations in a single response.
+/// It is ideal for use cases such as personalized homepage sections (*Articles from <category>*), *Because You Watched <movie>*, or *Artists Related to Your Favorite Artist <artist>*.
+/// See detailed **examples and configuration guidance** in the [Composite Scenarios documentation](https://docs.recombee.com/scenarios#composite-recommendations).
+/// **Structure**
+/// The endpoint operates in two stages:
+/// 1. Recommends the *source* (e.g., an Item Segment or item) to the user.
+/// 2. Recommends *results* (items or Item Segments) related to that *source*.
+/// For example, *Articles from <category>* can be decomposed into:
+///   - [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-item-segments-to-user) to find the category.
+///   - [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment) to recommend articles from that category.
+/// Since the first step uses [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-items-to-user), you must include the `userId` parameter in the *Composite Recommendation* request.
+/// Each *Composite Recommendation* counts as a single recommendation API request for billing.
+/// **Stage-specific Parameters**
+/// Additional parameters can be supplied via [sourceSettings](https://docs.recombee.com/api#composite-recommendation-param-sourceSettings) and [resultSettings](https://docs.recombee.com/api#composite-recommendation-param-resultSettings).
+/// In the example above:
+///   - `sourceSettings` may include any parameter valid for [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-items-to-user) (e.g., `filter`, `booster`).
+///   - `resultSettings` may include any parameter valid for [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment).
+/// See [this example](https://docs.recombee.com/api#composite-recommendation-example-setting-parameters-for-individual-stages) for more details.
+public struct CompositeRecommendation: Request {
+    public typealias Response = CompositeRecommendationResponse
+
+    /// Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
+    /// You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
+    /// The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
+
+    public let scenario: String
+
+    /// Number of items to be recommended (N for the top-N recommendation).
+
+    public let count: Int
+
+    /// ID of the item for which the recommendations are to be generated.
+
+    public var itemId: String? = nil
+
+    /// ID of the user for which the recommendations are to be generated.
+
+    public var userId: String? = nil
+
+    /// 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).
+
+    public var logic: Logic? = nil
+
+    /// ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
+
+    public var segmentId: String? = nil
+
+    /// If the entity for the source recommendation does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that entity, as the entity will be already known to the system.
+
+    public var cascadeCreate: Bool? = true
+
+    /// Parameters applied for recommending the *Source* stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the *Source*.
+
+    public var sourceSettings: CompositeRecommendationStageParameters? = nil
+
+    /// Parameters applied for recommending the *Result* stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the *Result*.
+
+    public var resultSettings: CompositeRecommendationStageParameters? = nil
+
+    /// Dictionary of custom options.
+
+    public var expertSettings: JSONDictionary? = nil
+
+    /// Initializes CompositeRecommendation request
+    /// - Parameters:
+    ///   - scenario: Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
+    /// You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
+    /// The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
+    ///   - count: Number of items to be recommended (N for the top-N recommendation).
+    ///   - itemId: ID of the item for which the recommendations are to be generated.
+    ///   - userId: ID of the user for which the recommendations are to be generated.
+    ///   - 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).
+    ///   - segmentId: ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
+    ///   - cascadeCreate: If the entity for the source recommendation does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that entity, as the entity will be already known to the system.
+    ///   - sourceSettings: Parameters applied for recommending the *Source* stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the *Source*.
+    ///   - resultSettings: Parameters applied for recommending the *Result* stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the *Result*.
+    ///   - expertSettings: Dictionary of custom options.
+
+    public init(scenario: String, count: Int, itemId: String? = nil, userId: String? = nil, logic: Logic? = nil, segmentId: String? = nil, cascadeCreate: Bool? = true, sourceSettings: CompositeRecommendationStageParameters? = nil, resultSettings: CompositeRecommendationStageParameters? = nil, expertSettings: JSONDictionary? = nil) {
+        self.scenario = scenario
+        self.count = count
+        self.itemId = itemId
+        self.userId = userId
+        self.logic = logic
+        self.segmentId = segmentId
+        self.cascadeCreate = cascadeCreate
+        self.sourceSettings = sourceSettings
+        self.resultSettings = resultSettings
+        self.expertSettings = expertSettings
+    }
+
+    /// The API path for the request
+    public var path: String { "/recomms/composite/" }
+
+    /// The HTTP method used to send the request
+    public var method: HTTPMethod { .POST }
+
+    /// Timeout interval in seconds.
+    public var timeout: TimeInterval = 3.0
+
+    /// Whether to enforce HTTPS for this request.
+    public var ensureHttps: Bool { false }
+
+    /// Query parameters to be included in the URL
+    public var queryParameters: [String: Any]? {
+        return [:]
+    }
+
+    /// The body of the request as a dictionary
+    public var bodyParameters: [String: Any]? {
+        var body: [String: Any] = [
+            "scenario": scenario,
+            "count": count,
+        ]
+
+        if let itemId = itemId {
+            body["itemId"] = itemId
+        }
+
+        if let userId = userId {
+            body["userId"] = userId
+        }
+
+        if let logic = logic {
+            body["logic"] = logic
+        }
+
+        if let segmentId = segmentId {
+            body["segmentId"] = segmentId
+        }
+
+        if let cascadeCreate = cascadeCreate {
+            body["cascadeCreate"] = cascadeCreate
+        }
+
+        if let sourceSettings = sourceSettings {
+            body["sourceSettings"] = sourceSettings
+        }
+
+        if let resultSettings = resultSettings {
+            body["resultSettings"] = resultSettings
+        }
+
+        if let expertSettings = expertSettings {
+            body["expertSettings"] = expertSettings
+        }
+
+        return body
+    }
+}

Sources/RecombeeClient/Requests/CompositeRecommendation.swift

@@ -6,6 +6,8 @@ import Foundation
 
 /// Merges interactions (purchases, ratings, bookmarks, detail views ...) of two different users under a single user ID. This is especially useful for online e-commerce applications working with anonymous users identified by unique tokens such as the session ID. In such applications, it may often happen that a user owns a persistent account, yet accesses the system anonymously while, e.g., putting items into a shopping cart. At some point in time, such as when the user wishes to confirm the purchase, (s)he logs into the system using his/her username and password. The interactions made under anonymous session ID then become connected with the persistent account, and merging these two becomes desirable.
 /// Merging happens between two users referred to as the *target* and the *source*. After the merge, all the interactions of the source user are attributed to the target user, and the source user is **deleted**.
+/// By default, the *Merge Users* request is only available from server-side integrations for security reasons, to prevent potential abuse.
+/// If you need to call this request from a client-side environment (such as a web or mobile app), please contact our support and request access to enable this feature for your database.
 public struct MergeUsers: Request {
     public typealias Response = StringResponseBinding