Add invite-only group classes

Group classes can now be marked invite-only (us_offerings.access_mode).
Invite-only classes are hidden from the public catalog and reachable only
when the instructor lets someone in via one of three paths, managed from
My Lessons -> My Group Classes:

- Add students directly: enrols them now with a pending payment.
- Make available: grants registered students access to self-enrol through
  the normal paid flow (multi-select, emailed a notice).
- Invite by email: tokenised registration invite tied to the class for a
  non-account address; after they register the class becomes enrollable.
  Reuses an existing pending invite instead of sending a second link.

New us_group_access table records grants; GET /offerings merges granted
invite-only classes for the caller; enrolment requires a grant
(403 invite_required) and flips it to enrolled on success.

composer test (487), composer lint, composer cs all pass.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

src/Offering/OfferingEndpoint.php

@@ -4,11 +4,15 @@ declare(strict_types=1);
 namespace Unsupervised\Schedular\Offering;
 
 use Unsupervised\Schedular\Auth\RoleManager;
+use Unsupervised\Schedular\GroupClass\GroupAccessRepository;
 use Unsupervised\Schedular\Val;
 
 class OfferingEndpoint {
 
-	public function __construct( private OfferingRepository $repository ) {}
+	public function __construct(
+		private OfferingRepository $repository,
+		private GroupAccessRepository $access,
+	) {}
 
 	/**
 	 * Registers this endpoint's REST routes.
@@ -62,16 +66,53 @@ class OfferingEndpoint {
 	}
 
 	public function index( \WP_REST_Request $request ): \WP_REST_Response {
-		$offerings = $this->repository->findAll(
-			Val::int( $request->get_param( 'instructor_id' ) ),
-			Val::string( $request->get_param( 'kind' ) ),
-			activeOnly: true,
-		);
+		$instructorId = Val::int( $request->get_param( 'instructor_id' ) );
+		$kind         = Val::string( $request->get_param( 'kind' ) );
+
+		// The public catalogue is public offerings only; invite-only classes are
+		// hidden from it and surfaced separately to the students granted access.
+		$offerings = $this->repository->findAll( $instructorId, $kind, activeOnly: true, accessMode: Offering::ACCESS_PUBLIC );
+
+		foreach ( $this->grantedInviteOnly( $instructorId, $kind ) as $granted ) {
+			$offerings[] = $granted;
+		}
 
 		// Public listing: omit the private e-transfer destination email.
 		return new \WP_REST_Response( array_map( fn( Offering $o ) => $o->toArray( includeEtransferEmail: false ), $offerings ), 200 );
 	}
 
+	/**
+	 * The active invite-only offerings the caller has been granted access to,
+	 * matching the same instructor/kind filters as the public catalogue.
+	 *
+	 * @return list<Offering>
+	 */
+	private function grantedInviteOnly( int $instructorId, string $kind ): array {
+		$grantedIds = $this->access->findGrantedOfferingIds( get_current_user_id() );
+		if ( [] === $grantedIds ) {
+			return [];
+		}
+
+		$out = [];
+		foreach ( $grantedIds as $offeringId ) {
+			$offering = $this->repository->findById( $offeringId );
+
+			if (
+				null === $offering
+				|| ! $offering->isActive
+				|| ! $offering->isInviteOnly()
+				|| ( $instructorId > 0 && $offering->instructorId !== $instructorId )
+				|| ( '' !== $kind && $offering->kind !== $kind )
+			) {
+				continue;
+			}
+
+			$out[] = $offering;
+		}
+
+		return $out;
+	}
+
 	public function create( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
 		$title = sanitize_text_field( Val::string( $request->get_param( 'title' ) ) );
 		if ( '' === $title ) {
@@ -104,6 +145,7 @@ class OfferingEndpoint {
 			scheduleNote:    $this->nullableText( $request->get_param( 'schedule_note' ) ),
 			etransferEmail:  $this->nullableEmail( $request->get_param( 'etransfer_email' ) ),
 			cancellationCutoffHours: $this->nullableInt( $request->get_param( 'cancellation_cutoff_hours' ) ),
+			accessMode:      $this->accessMode( $request->get_param( 'access_mode' ), Offering::ACCESS_PUBLIC ),
 			isActive:        null === $request->get_param( 'is_active' ) ? true : (bool) $request->get_param( 'is_active' ),
 		);
 
@@ -150,6 +192,7 @@ class OfferingEndpoint {
 			scheduleNote:    $request->has_param( 'schedule_note' ) ? $this->nullableText( $request->get_param( 'schedule_note' ) ) : $existing->scheduleNote,
 			etransferEmail:  $request->has_param( 'etransfer_email' ) ? $this->nullableEmail( $request->get_param( 'etransfer_email' ) ) : $existing->etransferEmail,
 			cancellationCutoffHours: $request->has_param( 'cancellation_cutoff_hours' ) ? $this->nullableInt( $request->get_param( 'cancellation_cutoff_hours' ) ) : $existing->cancellationCutoffHours,
+			accessMode:      $request->has_param( 'access_mode' ) ? $this->accessMode( $request->get_param( 'access_mode' ), $existing->accessMode ) : $existing->accessMode,
 			isActive:        $request->has_param( 'is_active' ) ? (bool) $request->get_param( 'is_active' ) : $existing->isActive,
 			id:              $id,
 		);
@@ -212,6 +255,12 @@ class OfferingEndpoint {
 		return '' !== $email ? $email : null;
 	}
 
+	private function accessMode( mixed $value, string $fallback ): string {
+		$mode = Val::string( $value );
+
+		return in_array( $mode, Offering::VALID_ACCESS_MODES, true ) ? $mode : $fallback;
+	}
+
 	private function nullableInt( mixed $value ): ?int {
 		return ( null === $value || '' === $value ) ? null : Val::int( $value );
 	}