Look up users by email and document invitations

src/Id/Concerns/ManagesUsers.php

@@ -5,7 +5,9 @@ namespace Anikeen\Id\Concerns;
 
 use Anikeen\Id\ApiOperations\Get;
 use Anikeen\Id\ApiOperations\Post;
+use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Result;
+use Anikeen\Id\Support\AppRequest;
 use Throwable;
 
 trait ManagesUsers
@@ -24,20 +26,32 @@ trait ManagesUsers
     }
 
     /**
-     * Creates a new user on behalf of the current user.
+     * Finds the account of an email address or creates it (trusted apps, app token). The email
+     * address is matched regardless of case; a new account stores it in lower case, unverified.
+     * An existing account is returned unchanged (only a missing name is filled in).
      *
      * @param array{
-     *       first_name: null|string,
-     *       last_name: null|string,
-     *       username: null|string,
+     *       name?: null|string,
+     *       first_name?: null|string,
+     *       last_name?: null|string,
+     *       username?: null|string,
      *       email: string,
-     *       password: null|string
+     *       password?: null|string,
+     *       password_confirmation?: null|string,
+     *       send_invitation?: bool
      *   } $attributes The user data
-     *     - first_name:  The first name (optional)
-     *     - last_name:   The last name (optional)
-     *     - username:    The username (optional)
-     *     - email:       The email (required)
-     *     - password:    The password (optional, can be reset by the user if not provided)
+     *     - name:                  The display name (optional)
+     *     - first_name:            The first name (optional, joined with last_name into name)
+     *     - last_name:             The last name (optional, joined with first_name into name)
+     *     - username:              The username (optional)
+     *     - email:                 The email (required)
+     *     - password:              The password (optional, can be reset by the user if not provided)
+     *     - password_confirmation: Defaults to password
+     *     - send_invitation:       Send the user an invitation mail with a link to set a password
+     *                              (optional, only when this call created the account without a
+     *                              password, never for an existing account)
+     * @return Result `data` is the user plus `created` (this call created the account) and
+     *     `invitation_sent` (the invitation mail was sent); 201 when created, 200 when it existed
      * @throws Throwable
      */
     public function createUser(array $attributes): Result
@@ -57,6 +71,30 @@ trait ManagesUsers
         return $this->asApp()->post('v1/admin/users', $attributes);
     }
 
+    /**
+     * Looks up the account of an email address without creating or changing anything (trusted
+     * apps, app token). The email address is matched regardless of case.
+     *
+     * `data` is `object{id: string, name: ?string, email: string, email_verified: bool,
+     * has_billing_address: bool}`.
+     *
+     * @return Result|null null when no account uses the email address
+     * @throws ApiException when the request fails for another reason
+     */
+    public function findUserByEmail(string $email): ?Result
+    {
+        try {
+            return AppRequest::send('POST', 'v1/admin/users/lookup', ['email' => $email]);
+        } catch (ApiException $e) {
+            // only Anikeen ID's own answer means "no account", not e.g. an unknown route
+            if ($e->isNotFound() && $e->error === 'user_not_found') {
+                return null;
+            }
+
+            throw $e;
+        }
+    }
+
     /**
      * Find the user of a social login or create it (trusted apps, app token).
      *