Merge Command supports optional timestamp argument. (#136)

Merge Command supports optional timestamp argument.

CHANGELOG.md

@@ -5,6 +5,9 @@
 <!-- There is always Unreleased section on the top. Subsections (Added, Changed, Fixed, Removed) should be added as needed. -->
 
 ## Unreleased
+### Added
+- Added optional argument timestamp to UserMerge command.
+
 
 ## 4.0.0 - 2020-12-17
 ### Added

README.md

@@ -175,7 +175,7 @@ $response = $matej->request()
     ->addItemProperty(ItemProperty::create('item-id', ['valid_from' => time(), 'title' => 'Title']))
     ->addItemProperties([/* array of ItemProperty objects */])
     // Merge user
-    ->addUserMerge(UserMerge::mergeInto('target-user-id', 'source-user-id'))
+    ->addUserMerge(UserMerge::mergeInto('target-user-id', 'source-user-id', 1629361884))
     ->addUserMerges([/* array of UserMerge objects */])
     ->send();
 ```
@@ -186,6 +186,16 @@ If that happens, you should resend the entire request later, as no commands were
 
 This has been implemented so that we don't lose any pushed data. Simple sleep of 100ms should be enough.
 
+### Merging users
+
+You can merge users using the `UserMerge` command. The first argument is the target user ID and the second argument is the ID
+of source user. When you merge two users, Matej will move all interactions and history of the source user and assign them to
+the target user. The source user is then removed.
+
+Optionally, you may send a third argument with a timestamp of when the merge happened.
+
+**The timestamp will be required in the future. We reccommend you to send it which will make future upgrades of the Matej client easier for you.**
+
 ### Requesting recommendations
 
 You can request 4 types of recommendations from Matej. Each of them is represented by a specific recommendation command class:

src/Model/Command/UserMerge.php

@@ -14,11 +14,14 @@ class UserMerge extends AbstractCommand implements UserAwareInterface
     private $sourceUserId;
     /** @var string */
     private $targetUserId;
+    /** @var int */
+    private $timestamp;
 
-    private function __construct(string $targetUserId, string $sourceUserId)
+    private function __construct(string $targetUserId, string $sourceUserId, int $timestamp = null)
     {
         $this->setTargetUserId($targetUserId);
         $this->setSourceUserId($sourceUserId);
+        $this->setTimestamp($timestamp ?? time());
 
         $this->assertUserIdsNotEqual();
     }
@@ -28,19 +31,19 @@ private function __construct(string $targetUserId, string $sourceUserId)
      *
      * @return static
      */
-    public static function mergeInto(string $targetUserId, string $sourceUserIdToBeDeleted): self
+    public static function mergeInto(string $targetUserId, string $sourceUserIdToBeDeleted, int $timestamp = null): self
     {
-        return new static($targetUserId, $sourceUserIdToBeDeleted);
+        return new static($targetUserId, $sourceUserIdToBeDeleted, $timestamp);
     }
 
     /**
      * Merge source user into target user AND DELETE SOURCE USER.
      *
      * @return static
      */
-    public static function mergeFromSourceToTargetUser(string $sourceUserIdToBeDeleted, string $targetUserId): self
+    public static function mergeFromSourceToTargetUser(string $sourceUserIdToBeDeleted, string $targetUserId, int $timestamp = null): self
     {
-        return new static($targetUserId, $sourceUserIdToBeDeleted);
+        return new static($targetUserId, $sourceUserIdToBeDeleted, $timestamp);
     }
 
     public function getUserId(): string
@@ -67,6 +70,13 @@ protected function setTargetUserId(string $targetUserId): void
         $this->targetUserId = $targetUserId;
     }
 
+    protected function setTimestamp(int $timestamp): void
+    {
+        Assertion::greaterThan($timestamp, 0);
+
+        $this->timestamp = $timestamp;
+    }
+
     private function assertUserIdsNotEqual(): void
     {
         Assertion::notEq(
@@ -86,6 +96,7 @@ protected function getCommandParameters(): array
         return [
             'target_user_id' => $this->targetUserId,
             'source_user_id' => $this->sourceUserId,
+            'timestamp' => $this->timestamp,
         ];
     }
 }

tests/unit/Model/Command/UserMergeTest.php

@@ -12,12 +12,13 @@ public function shouldGenerateCorrectSignature(): void
     {
         $sourceUserId = 'source-user';
         $targetUserId = 'target-user';
+        $timestamp = 1629362296;
 
-        $command = UserMerge::mergeInto($targetUserId, $sourceUserId);
-        $this->assertUserMergeCommand($command, $sourceUserId, $targetUserId);
+        $command = UserMerge::mergeInto($targetUserId, $sourceUserId, $timestamp);
+        $this->assertUserMergeCommand($command, $sourceUserId, $targetUserId, $timestamp);
 
-        $command = UserMerge::mergeFromSourceToTargetUser($sourceUserId, $targetUserId);
-        $this->assertUserMergeCommand($command, $sourceUserId, $targetUserId);
+        $command = UserMerge::mergeFromSourceToTargetUser($sourceUserId, $targetUserId, $timestamp);
+        $this->assertUserMergeCommand($command, $sourceUserId, $targetUserId, $timestamp);
     }
 
     public function shouldThrowExceptionWhenMergingSameUsers(): void
@@ -33,7 +34,7 @@ public function shouldThrowExceptionWhenMergingSameUsers(): void
      *
      * @param UserMerge $command
      */
-    private function assertUserMergeCommand($command, string $sourceUserId, string $targetUserId): void
+    private function assertUserMergeCommand($command, string $sourceUserId, string $targetUserId, int $timestamp): void
     {
         $this->assertInstanceOf(UserMerge::class, $command);
         $this->assertSame(
@@ -42,6 +43,7 @@ private function assertUserMergeCommand($command, string $sourceUserId, string $
                 'parameters' => [
                     'target_user_id' => $targetUserId,
                     'source_user_id' => $sourceUserId,
+                    'timestamp' => $timestamp,
                 ],
             ],
             $command->jsonSerialize()