feat(users): add email to MergeIdentifier object

src/Object/Users/MergeIdentifier.php

@@ -12,16 +12,37 @@ class MergeIdentifier extends BaseObject
 
     public ?UserAlias $user_alias = null;
 
+    public ?string $email = null;
+
+    /** @var ?string[] */
+    public ?array $prioritization = null;
+
     public function validate(bool $strict): void
     {
         parent::validate($strict);
 
-        if (null === $this->external_id && null === $this->user_alias) {
-            throw new ValidationException('One of "external_id" or "user_alias" fields is required');
+        if (null === $this->external_id && null === $this->user_alias && null === $this->email) {
+            throw new ValidationException('One of "external_id", "user_alias" or "email" fields is required');
+        }
+
+        if (\count(array_filter([$this->external_id, $this->user_alias, $this->email])) > 1) {
+            throw new ValidationException('Only one of "external_id", "user_alias" and "email" fields must be set');
         }
 
-        if (null !== $this->external_id && null !== $this->user_alias) {
-            throw new ValidationException('Only one of "external_id" and "user_alias" fields must be set');
+        if (null !== $this->email && null === $this->prioritization) {
+            throw new ValidationException('If an "email" is specified as an identifier, an additional "prioritization" value is required');
+        }
+
+        if (null !== $this->prioritization) {
+            foreach ($this->prioritization as $prioritizationItem) {
+                if (!in_array($prioritizationItem, ['identified', 'unidentified', 'most_recently_updated'])) {
+                    throw new ValidationException('The allowed values for the "prioritization" array are: "identified", "unidentified", "most_recently_updated"');
+                }
+            }
+
+            if (\count(array_intersect($this->prioritization, ['identified', 'unidentified'])) > 1) {
+                throw new ValidationException('Only one of "identified" and "unidentified" options may exist in the prioritization array');
+            }
         }
 
         $this->user_alias?->validate($strict);

tests/Object/Users/MergeIdentifierTest.php

@@ -52,4 +52,54 @@ public function validProvider(): array
             [$mergeIdentifier],
         ];
     }
+
+    /**
+     * @dataProvider validEmailIdentifierProvider
+     * @doesNotPerformAssertions
+     */
+    public function testValidEmailIdentifier(MergeIdentifier $mergeIdentifier): void
+    {
+        $mergeIdentifier->validate(true);
+    }
+
+    public function validEmailIdentifierProvider(): array
+    {
+        $mergeIdentifier = new MergeIdentifier();
+        $mergeIdentifier->email = '[email protected]';
+        $mergeIdentifier->prioritization = ['unidentified', 'most_recently_updated'];
+
+        return [
+            [$mergeIdentifier],
+        ];
+    }
+
+    /**
+     * @dataProvider invalidEmailIdentifierProvider
+     */
+    public function testInvalidEmailIdentifier(MergeIdentifier $mergeIdentifier): void
+    {
+        $this->expectException(ValidationException::class);
+
+        $mergeIdentifier->validate(false);
+    }
+
+    public function invalidEmailIdentifierProvider(): array
+    {
+        $mergeIdentifier1 = new MergeIdentifier();
+        $mergeIdentifier1->email = '[email protected]';
+
+        $mergeIdentifier2 = new MergeIdentifier();
+        $mergeIdentifier2->email = '[email protected]';
+        $mergeIdentifier2->prioritization = ['email'];
+
+        $mergeIdentifier3 = new MergeIdentifier();
+        $mergeIdentifier3->email = '[email protected]';
+        $mergeIdentifier3->prioritization = ['identified', 'unidentified'];
+
+        return [
+            [$mergeIdentifier1],
+            [$mergeIdentifier2],
+            [$mergeIdentifier3],
+        ];
+    }
 }