Add multi-use group invite links with expiry and auto-approval on email confirmation

A studio admin can generate a shareable group invite link (e.g. for a
newsletter) from the Invites page, choosing a required expiry date. Anyone
with the link may register while it is valid, in any registration mode: the
form collects their own email, they must confirm it via the usual hashed
token, and confirming approves the account immediately — group signups never
enter the Pending Students queue.

- us_invites grows kind (personal/group) and expires_at; an explicit expiry
  wins over the personal 14-day window. Group links stay pending (multi-use)
  until revoked or expired.
- RegistrationPage: group signups create the account pending with the
  us_auto_approve marker and send the confirmation email; no auto-login.
- EmailConfirmationHandler: auto-approve accounts are approved on
  confirmation, emailed the approved notice, and redirected to a new
  us_confirmed=ready notice with a sign-in link.

Closes #77

Co-Authored-By: Claude Fable 5 <[email protected]>

tests/Unit/Auth/EmailConfirmationHandlerTest.php

@@ -4,9 +4,11 @@ declare(strict_types=1);
 namespace Unsupervised\Schedular\Tests\Unit\Auth;
 
 use Brain\Monkey\Functions;
+use Mockery;
 use Unsupervised\Schedular\Auth\EmailConfirmationHandler;
 use Unsupervised\Schedular\Auth\RegistrationController;
 use Unsupervised\Schedular\Auth\RegistrationMailer;
+use Unsupervised\Schedular\Auth\RegistrationStatus;
 use Unsupervised\Schedular\Payment\StudioSettings;
 use Unsupervised\Schedular\Tests\Unit\TestCase;
 
@@ -22,9 +24,84 @@ class EmailConfirmationHandlerTest extends TestCase
     protected function tearDown(): void
     {
         unset($_REQUEST['action']);
+        $_GET = [];
         parent::tearDown();
     }
 
+    /**
+     * Stub everything maybeConfirm() needs for a valid token belonging to user
+     * 9, with wp_safe_redirect throwing so the redirect URL can be asserted.
+     *
+     * @param bool $autoApprove Whether user 9 carries the auto-approve marker.
+     */
+    private function stubConfirmContext(bool $autoApprove): void
+    {
+        $this->stubMode(StudioSettings::MODE_INVITE);
+        Functions\when('is_admin')->justReturn(false);
+        Functions\when('sanitize_text_field')->returnArg();
+        Functions\when('get_permalink')->justReturn('http://wp/register/');
+        Functions\when('add_query_arg')->alias(static fn (string $k, string $v, string $u): string => $u . '?' . $k . '=' . $v);
+        Functions\when('get_users')->justReturn([9]);
+        Functions\when('get_user_meta')->alias(static function (int $id, string $key) use ($autoApprove) {
+            if ($key === RegistrationStatus::META_CONFIRM_EXPIRES) {
+                return '2030-01-01 00:00:00';
+            }
+            if ($key === RegistrationStatus::META_AUTO_APPROVE) {
+                return $autoApprove ? '1' : '';
+            }
+            return '';
+        });
+        Functions\when('update_user_meta')->justReturn(true);
+        Functions\when('delete_user_meta')->justReturn(true);
+        Functions\when('wp_safe_redirect')->alias(static function (string $url): void {
+            throw new \RuntimeException('redirect:' . $url);
+        });
+
+        $_GET['us_confirm'] = 'rawtoken';
+    }
+
+    public function testConfirmAutoApprovesGroupLinkSignupWithoutAdminReview(): void
+    {
+        $this->stubConfirmContext(true);
+
+        $user = Mockery::mock(\WP_User::class);
+        Functions\when('get_user_by')->justReturn($user);
+
+        $mailer = Mockery::mock(RegistrationMailer::class);
+        $mailer->shouldReceive('sendApproved')->once()->with($user)->andReturn(true);
+        $mailer->shouldNotReceive('notifyAdminsPending');
+
+        $handler = new EmailConfirmationHandler(new StudioSettings(), $mailer);
+
+        try {
+            $handler->maybeConfirm();
+            self::fail('Expected a redirect');
+        } catch (\RuntimeException $e) {
+            self::assertStringContainsString('us_confirmed=ready', $e->getMessage());
+        }
+    }
+
+    public function testConfirmWithoutAutoApproveNotifiesAdminsAndStaysPending(): void
+    {
+        $this->stubConfirmContext(false);
+
+        $user = Mockery::mock(\WP_User::class);
+        Functions\when('get_user_by')->justReturn($user);
+
+        $mailer = Mockery::mock(RegistrationMailer::class);
+        $mailer->shouldReceive('notifyAdminsPending')->once()->with($user)->andReturn(true);
+        $mailer->shouldNotReceive('sendApproved');
+
+        $handler = new EmailConfirmationHandler(new StudioSettings(), $mailer);
+
+        try {
+            $handler->maybeConfirm();
+            self::fail('Expected a redirect');
+        } catch (\RuntimeException $e) {
+            self::assertStringContainsString('us_confirmed=1', $e->getMessage());
+        }
+    }
+
     private function handler(): EmailConfirmationHandler
     {
         return new EmailConfirmationHandler(new StudioSettings(), new RegistrationMailer());