v4.4.0: Customer Inventory Enhancements, Rule Failure Reasons and Import Endpoints (#20)

<i id="toc"></i>
## Summary
  - [Management API](#user-content-management-api)
    - [Expose Import Endpoints](#user-content-expose-import-endpoints)
    - [Introduce `updateReferral` Endpoint](#user-content-update-referral)
  - [Integration API](#user-content-integration-api)
    - [Improve Responses Transparency](#user-content-improve-responses)
    - [Extended Customer Inventory Endpoint](#user-content-customer-inventory)
    - [Attach Loyalty Program ID in responses](#user-content-attach-loyalty-id)
    - [A reminder of The Deprecation Notice: Integration API@v1 endpoints](#user-content-deprecation-reminder)

<i id="management-api"></i>
## Management API

<i id="expose-import-endpoints"></i>
### Expose import endpoints as integral part of the SDK

All of our CSV import endpoints are accessible via the Web Application from the corresponding entity pages (refer to our [Help Center](https://help.talon.one/hc/en-us/articles/360010114599-Import-and-Export-Coupons#ImportCoupons) for an example regarding Coupons).

Now these are also available endpoints as part of the SDK (links to our developer docs):
  - [Coupons Import](https://developers.talon.one/Management-API/API-Reference#importCoupons)
  - [Referrals Import](https://developers.talon.one/Management-API/API-Reference#importReferrals)
  - [Loyalty Points Import](https://developers.talon.one/Management-API/API-Reference#importLoyaltyPoints)
  - [Giveaway Codes Import](https://developers.talon.one/Management-API/API-Reference#importPoolGiveaways)

Example code snippet demonstrating import coupons using a CSV file:
```java
// ...preparing api client...
// An example could be seen at the repository's README file: https://github.com/talon-one/TalonOneJavaSdk#management-api

try {
  Integer applicationId = 1;
  Integer campaignId = 184;
  File upFile = new File("path/to/coupons.csv");
  ModelImport response = api.importCoupons(applicationId, campaignId, upFile);
} catch (FileNotFoundException e) {
  System.out.println("CSV file was not found.");
  e.printStackTrace();
} catch (Exception e) {
  System.out.println("Error while importing coupons.");
  System.out.println(e);
}
```

[☝️ Back to Table of Contents](#user-content-toc)

<i id="update-referral"></i>
### Introduce [`updateReferral`](https://developers.talon.one/Management-API/API-Reference#updateReferral) Endpoint

We introduced an endpoint to update referrals in order to allow updating their scheduling, usage limits and custom attributes attached to them.

Please consult [the endpoint reference](https://developers.talon.one/Management-API/API-Reference#updateReferral) in our developer docs for more details.

[☝️ Back to Table of Contents](#user-content-toc)

<i id="integration-api"></i>
## Integration API

<i id="improve-responses"></i>
### Improve Responses Transparency
We are constantly extending and improving our integration API to provide our consumers with the best transparency regarding what exactly has happened within their requests.

We have added new data points to our **v2 endpoints** effects in order to improve the transparency we aspire for:
 - If an effect was triggered because of a specific coupon the effect will now include this coupon ID, see [`Effect.md`](https://github.com/talon-one/TalonOneJavaSdk/blob/e63620817d5e7bb07e0b6bd9ef515a6b38257524/docs/Effect.md#L15)
 - When a coupon is rejected we attach more details regarding the origin of the failure in [`RejectCouponEffectProps`](https://github.com/talon-one/TalonOneJavaSdk/blob/1042bd65a2a48296d38591f652fa967fe096af1c/docs/RejectCouponEffectProps.md#L12-L14):
    - `conditionIndex` - The index of the condition that caused the rejection of the coupon
    - `effectIndex` - The index of the effect that caused the rejection of the coupon
    - `details` - More details about the failure (if available)
  - The same applies for referrals, when a referral is rejected we attach more details regarding the origin of the failure in  [`RejectReferralEffectProps`](https://github.com/talon-one/TalonOneJavaSdk/blob/1042bd65a2a48296d38591f652fa967fe096af1c/docs/RejectReferralEffectProps.md#L12-L14):
    - `conditionIndex` - The index of the condition that caused the rejection of the referral
    - `effectIndex` - The index of the effect that caused the rejection of the referral
    - `details` - More details about the failure (if available)

Moreover, we have introduced a new [response content](https://github.com/talon-one/TalonOneJavaSdk/blob/1042bd65a2a48296d38591f652fa967fe096af1c/src/main/java/one/talon/model/IntegrationRequest.java#L61), `RuleFailureReasons`, which when requested will attach to the response a collection containing **all failed rules**, with details (see the [`RuleFailureReason` model](https://github.com/talon-one/TalonOneJavaSdk/blob/1042bd65a2a48296d38591f652fa967fe096af1c/docs/RuleFailureReason.md) to help narrowing down failures and further debugging efforts to a specific single condition or effect that caused the failure. 

_One "gotcha" to keep in mind_: in order to maximize transparency, and due to the fact that we do not know in advance which campaign in the application the request targets, the list contains a collection of **all** failure reasons.

Meaning that, it might have "white noise" with data about failures that could be considered as "obvious" to the consumer. Therefore, we suggest always filtering the list by the campaign id that was expected to trigger and did not.

[☝️ Back to Table of Contents](#user-content-toc)

<i id="customer-inventory"></i>
### Extended Customer Inventory Endpoint
We have added a couple of useful data points to our customer inventory to make integration even simpler.

#### ⚠️⚠️ It involves a breaking change when calling the operation
```diff
IntegrationApi apiInstance = new IntegrationApi(defaultClient);
String integrationId = "integrationId_example"; // String | The custom identifier for this profile, must be unique within the account.
Boolean profile = true; // Boolean | optional flag to decide if you would like customer profile information in the response
Boolean referrals = true; // Boolean | optional flag to decide if you would like referral information in the response
Boolean coupons = true; // Boolean | optional flag to decide if you would like coupon information in the response
Boolean loyalty = true; // Boolean | optional flag to decide if you would like loyalty information in the response
+Boolean giveaways = true; // Boolean | optional flag to decide if you would like giveaways information in the response

- CustomerInventory result = apiInstance.getCustomerInventory(integrationId, profile, referrals, coupons, loyalty);
+ CustomerInventory result = apiInstance.getCustomerInventory(integrationId, profile, referrals, coupons, loyalty, giveaways);
// ...
```

We are aware of the inconvenience, and as explained in #16, we are working on a better and improved implementation to avoid these breaking changes in the future.

As one can see, customer inventory now has the ability to return giveaway codes that belong to the profile in query.
In order to learn more about setting up such campaigns refer to [this help center article](https://help.talon.one/hc/en-us/articles/360020631099-Giveaway-Campaigns) and [this developer docs tutorial](https://developers.talon.one/Tutorials/creating-giveaways).

We have also extended the coupons objects that are returned as part of the inventory and attached these two useful data-points to each returned coupon:

  - `profileRedemptionCount` - holds the number of times the coupon was redeemed by the profile
  - `state` - holds the state of the coupon and can be one of the below values:
    - **_active_**: reserved coupons that are neither pending nor used nor expired, and have a non-exhausted limit counter
    - **_used_**: coupons that are not pending, and have reached their redemption limit or were redeemed by the profile before expiration
    - **_expired_**: all non-pending, non-active, non-used coupons that were not redeemed by the profile
    - **_pending_**: coupons that have a start date in the future

[☝️ Back to Table of Contents](#user-content-toc)

<i id="attach-loyalty-id"></i>
### Attach Loyalty Program ID in responses

When the consumer requires that the response will contain the details of loyalty programs involved in processing the requests, we now attach the identifier of the loyalty program to the returned [`LoyaltyProgramLedgers` models](https://github.com/talon-one/TalonOneJavaSdk/blob/1042bd65a2a48296d38591f652fa967fe096af1c/docs/LoyaltyProgramLedgers.md#L10).

The idea behind attaching the identifier is to help streamline further potential requests to our Management API with regard to details about a Loyalty Program, for example [getLoyaltyStatistics](https://developers.talon.one/Management-API/API-Reference#getLoyaltyStatistics) or [getLoyaltyPoints](https://developers.talon.one/Management-API/API-Reference#getLoyaltyPoints), that require the program identifier as part of the URI of the endpoint.

[☝️ Back to Table of Contents](#user-content-toc)

<i id="deprecation-reminder"></i>
### ⚠️ A reminder of The Deprecation Notice: Integration API@v1 endpoints
The deprecation was introduced already in the last release of the SDK, here is a kind reminder of the deprecation notices for Integration API@v1 endpoints:

 - [Update a Customer Session (V1)](https://github.com/talon-one/TalonOneJavaSdk/blob/1042bd65a2a48296d38591f652fa967fe096af1c/docs/IntegrationApi.md#updatecustomersession)
 - [Update a Customer Profile (V1)](https://github.com/talon-one/TalonOneJavaSdk/blob/1042bd65a2a48296d38591f652fa967fe096af1c/docs/IntegrationApi.md#updatecustomerprofile)

These endpoints will be flagged deprecated on _15.07.2021_, meaning support for requests to these endpoints will end on that date. **We will not remove the endpoints**, and they will still be accessible for you to use.

We highly encourage migrating to the correspondent v2 endpoints for easier and more granular integration, as well as new features support (See [our developer docs section](https://developers.talon.one/Getting-Started/APIV2) about API V2.0).

[☝️ Back to Table of Contents](#user-content-toc)

Author: altJake

Makefile

@@ -22,3 +22,11 @@ bundle:
 	cp target/talon-one-client-$(VERSION).jar $(DIST)
 
 prepare: build bundle
+
+testenv:
+	docker run \
+		--rm -it \
+		-v $(PWD):/tmp/talon-client \
+		-w "/tmp/talon-client" \
+		maven:3.5.2-jdk-9-slim \
+		/bin/bash

README.md

@@ -3,7 +3,7 @@ apply plugin: 'eclipse'
 apply plugin: 'java'
 
 group = 'one.talon'
-version = '4.3.1'
+version = '4.4.0'
 
 buildscript {
     repositories {

api/openapi.yaml

@@ -2,7 +2,7 @@ lazy val root = (project in file(".")).
   settings(
     organization := "one.talon",
     name := "talon-one-client",
-    version := "4.3.1",
+    version := "4.4.0",
     scalaVersion := "2.11.4",
     scalacOptions ++= Seq("-feature"),
     javacOptions in compile ++= Seq("-Xlint:deprecation"),

build.gradle

@@ -0,0 +1,18 @@
+
+
+# ApplicationCampaignStats
+
+Provides statistics regarding an application's campaigns
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**draft** | **Integer** | Number of draft campaigns | 
+**disabled** | **Integer** | Number of disabled campaigns | 
+**scheduled** | **Integer** | Number of scheduled campaigns | 
+**running** | **Integer** | Number of running campaigns | 
+**expired** | **Integer** | Number of expired campaigns | 
+**archived** | **Integer** | Number of archived campaigns | 
+
+
+

build.sbt

@@ -15,6 +15,7 @@ Name | Type | Description | Notes
 **type** | **String** | A string representing the event. Must not be a reserved event name. | 
 **attributes** | [**Object**](.md) | Additional JSON serialized data associated with the event. | 
 **effects** | **List<Object>** | An array containing the effects that were applied as a result of this event. | 
+**ruleFailureReasons** | [**List<RuleFailureReason>**](RuleFailureReason.md) | An array containing the rule failure reasons which happened during this event. |  [optional]
 
 
 

docs/ApplicationCampaignStats.md

@@ -0,0 +1,18 @@
+
+
+# ApplicationReferee
+
+
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**applicationId** | **Integer** | The ID of the application that owns this entity. | 
+**sessionId** | **String** | Integration ID of the session in which the customer redeemed the referral | 
+**advocateIntegrationId** | **String** | Integration ID of the Advocate's Profile | 
+**friendIntegrationId** | **String** | Integration ID of the Friend's Profile | 
+**code** | **String** | Advocate's referral code. | 
+**created** | [**OffsetDateTime**](OffsetDateTime.md) | Timestamp of the moment the customer redeemed the referral | 
+
+
+

docs/ApplicationEvent.md

@@ -34,6 +34,8 @@ CUSTOMERSESSION | "CustomerSession"
 CARTITEM | "CartItem"
 COUPON | "Coupon"
 EVENT | "Event"
+GIVEAWAY | "Giveaway"
+REFERRAL | "Referral"
 
 
 

docs/ApplicationReferee.md

@@ -0,0 +1,17 @@
+
+
+# AwardGiveawayEffectProps
+
+The properties specific to the \"awardGiveaway\" effect. This effect contains information on the giveaway item, and which profile it was awarded to.
+## Properties
+
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**poolId** | **Integer** | The ID of the giveaways pool the code was taken from. | 
+**poolName** | **String** | The name of the giveaways pool the code was taken from. | 
+**recipientIntegrationId** | **String** | The integration ID of the profile that was awarded the giveaway. | 
+**giveawayId** | **Integer** | The internal ID for the giveaway that was awarded. | 
+**code** | **String** | The giveaway code that was awarded. | 
+
+
+