From 330900a24654a39fedfde40a394708fe3fcb587e Mon Sep 17 00:00:00 2001
From: James Griffin <james@unsupervised.ca>
Date: Sun, 7 Jun 2026 10:31:11 -0300
Subject: [PATCH] Auto-redirect invite tokens to the registration page; rename
 invite button

- RegistrationPage::maybeRedirectToRegistrationPage() (hooked on
  template_redirect): any front-end request carrying a us_invite token is
  redirected to the configured registration page (token preserved), unless
  already there. Covers links shared before a page was selected; no-op when
  no page is set.
- Invites button text: "Send Invite" -> "Generate Invitation Link".
- Doc updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/features/account-registration.md |  7 +++++++
 src/Auth/RegistrationPage.php         | 25 +++++++++++++++++++++++++
 src/ShortcodeRegistrar.php            |  1 +
 templates/admin/invites.php           |  2 +-
 4 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/docs/features/account-registration.md b/docs/features/account-registration.md
index e136211..7c49b99 100644
--- a/docs/features/account-registration.md
+++ b/docs/features/account-registration.md
@@ -48,6 +48,13 @@ recorded in `us_policy_acceptances` with `registration_type = account` and
 ## Frontend Shortcode
 - `[us_student_register]` — the registration page. Shows the form for a valid pending invite; otherwise shows an "by invitation only" message (in `invite` mode).
 
+## Token Redirect
+A `template_redirect` handler (`RegistrationPage::maybeRedirectToRegistrationPage()`)
+sends any front-end request carrying a `us_invite` token to the configured
+registration page (preserving the token), unless it is already on that page. This
+covers invitation links generated/shared before a registration page was selected.
+No-op when no registration page is set.
+
 ## Capabilities
 - `manage_students` — manage invites (studio admin; administrators inherit it via the `user_has_cap` filter). Added to `RoleManager::STUDIO_ADMIN_CAPS`.
 
diff --git a/src/Auth/RegistrationPage.php b/src/Auth/RegistrationPage.php
index 0603231..bcafff2 100644
--- a/src/Auth/RegistrationPage.php
+++ b/src/Auth/RegistrationPage.php
@@ -52,6 +52,31 @@ class RegistrationPage {
 		return (string) ob_get_clean();
 	}
 
+	/**
+	 * Redirect to the configured registration page when an invite token lands
+	 * elsewhere (e.g. a link generated before the page was selected). Hooked on
+	 * `template_redirect`.
+	 */
+	public function maybeRedirectToRegistrationPage(): void {
+		if ( is_admin() ) {
+			return;
+		}
+
+		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only token used only to build the redirect target.
+		$token = sanitize_text_field( wp_unslash( $_GET['us_invite'] ?? '' ) );
+		if ( '' === $token ) {
+			return;
+		}
+
+		$pageId = (int) get_option( RegistrationController::OPTION_PAGE, 0 );
+		if ( $pageId <= 0 || is_page( $pageId ) ) {
+			return;
+		}
+
+		wp_safe_redirect( add_query_arg( 'us_invite', rawurlencode( $token ), (string) get_permalink( $pageId ) ) );
+		exit;
+	}
+
 	/**
 	 * Process the submitted registration. Returns true on success or an error
 	 * message string on failure.
diff --git a/src/ShortcodeRegistrar.php b/src/ShortcodeRegistrar.php
index 24a1762..0fb3501 100644
--- a/src/ShortcodeRegistrar.php
+++ b/src/ShortcodeRegistrar.php
@@ -32,6 +32,7 @@ class ShortcodeRegistrar {
 		add_shortcode( 'us_booking', [ $this->bookingPage, 'render' ] );
 		add_shortcode( 'us_student_login', [ $this->loginPage, 'render' ] );
 		add_shortcode( 'us_student_register', [ $this->registrationPage, 'render' ] );
+		add_action( 'template_redirect', [ $this->registrationPage, 'maybeRedirectToRegistrationPage' ] );
 		add_action( 'wp_enqueue_scripts', [ $this, 'enqueueAssets' ] );
 	}
 
diff --git a/templates/admin/invites.php b/templates/admin/invites.php
index 3861330..0d7c19f 100644
--- a/templates/admin/invites.php
+++ b/templates/admin/invites.php
@@ -55,7 +55,7 @@ if (! defined('ABSPATH')) {
                 <td><input type="email" name="email" id="email" class="regular-text" required></td>
             </tr>
         </table>
-        <?php submit_button(esc_html__('Send Invite', 'unsupervised-schedular')); ?>
+        <?php submit_button(esc_html__('Generate Invitation Link', 'unsupervised-schedular')); ?>
     </form>
 
     <h2><?php esc_html_e('Pending Invites', 'unsupervised-schedular'); ?></h2>