Add Offerings domain and studio-admin capabilities

Implements the offerings catalog (#1): private-lesson types and group
classes carrying pricing, billing mode (one_time/full_term), duration,
capacity, and term details. Adds the src/Offering/ domain (value object,
repository, REST endpoint, admin controller + template), the us_offerings
table, and an Offerings admin page.

Also lands the capability slice of #9: registers the us_studio_admin role
and the new capability strings (manage_instructors, manage_offerings,
manage_questions, manage_policies, manage_billing, view_all_payments,
view_own_payments, export_payments) so offering management gates correctly.

Tests: tests/Unit/Offering/ (value object + repository) and a studio-admin
case in RoleManagerTest. composer test, cs, and PHPStan level 6 all pass.

Refs #1 #9

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/Offering/OfferingEndpoint.php

@@ -0,0 +1,196 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Offering;
+
+use Unsupervised\Schedular\Auth\RoleManager;
+
+class OfferingEndpoint {
+
+	public function __construct( private OfferingRepository $repository ) {}
+
+	public function registerRoutes( string $route_namespace ): void {
+		register_rest_route(
+			$route_namespace,
+			'/offerings',
+			[
+				[
+					'methods'             => \WP_REST_Server::READABLE,
+					'callback'            => [ $this, 'index' ],
+					'permission_callback' => '__return_true',
+					'args'                => [
+						'instructor_id' => [
+							'type'    => 'integer',
+							'default' => 0,
+						],
+						'kind'          => [
+							'type'    => 'string',
+							'default' => '',
+						],
+					],
+				],
+				[
+					'methods'             => \WP_REST_Server::CREATABLE,
+					'callback'            => [ $this, 'create' ],
+					'permission_callback' => [ $this, 'canManage' ],
+				],
+			]
+		);
+
+		register_rest_route(
+			$route_namespace,
+			'/offerings/(?P<id>\d+)',
+			[
+				[
+					'methods'             => \WP_REST_Server::EDITABLE,
+					'callback'            => [ $this, 'update' ],
+					'permission_callback' => [ $this, 'canManage' ],
+				],
+				[
+					'methods'             => \WP_REST_Server::DELETABLE,
+					'callback'            => [ $this, 'delete' ],
+					'permission_callback' => [ $this, 'canManage' ],
+				],
+			]
+		);
+	}
+
+	public function index( \WP_REST_Request $request ): \WP_REST_Response {
+		$offerings = $this->repository->findAll(
+			(int) $request->get_param( 'instructor_id' ),
+			(string) $request->get_param( 'kind' ),
+			activeOnly: true,
+		);
+
+		return new \WP_REST_Response( array_map( fn( Offering $o ) => $o->toArray(), $offerings ), 200 );
+	}
+
+	public function create( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
+		$title = sanitize_text_field( (string) $request->get_param( 'title' ) );
+		if ( '' === $title ) {
+			return $this->invalid( __( 'A title is required.', 'unsupervised-schedular' ) );
+		}
+
+		$kind = (string) $request->get_param( 'kind' );
+		if ( ! in_array( $kind, Offering::VALID_KINDS, true ) ) {
+			return $this->invalid( __( 'Invalid offering kind.', 'unsupervised-schedular' ) );
+		}
+
+		$billingMode = (string) ( $request->get_param( 'billing_mode' ) ?? Offering::BILLING_ONE_TIME );
+		if ( ! in_array( $billingMode, Offering::VALID_BILLING_MODES, true ) ) {
+			return $this->invalid( __( 'Invalid billing mode.', 'unsupervised-schedular' ) );
+		}
+
+		$offering = new Offering(
+			instructorId:    get_current_user_id(),
+			kind:            $kind,
+			title:           $title,
+			priceCents:      absint( $request->get_param( 'price_cents' ) ),
+			currency:        sanitize_text_field( (string) ( $request->get_param( 'currency' ) ?? 'CAD' ) ),
+			billingMode:     $billingMode,
+			description:     $this->nullableText( $request->get_param( 'description' ) ),
+			durationMinutes: $this->nullableInt( $request->get_param( 'duration_minutes' ) ),
+			allowWeekly:     (bool) $request->get_param( 'allow_weekly' ),
+			capacity:        $this->nullableInt( $request->get_param( 'capacity' ) ),
+			termStart:       $this->nullableText( $request->get_param( 'term_start' ) ),
+			termEnd:         $this->nullableText( $request->get_param( 'term_end' ) ),
+			scheduleNote:    $this->nullableText( $request->get_param( 'schedule_note' ) ),
+			isActive:        null === $request->get_param( 'is_active' ) ? true : (bool) $request->get_param( 'is_active' ),
+		);
+
+		$id = $this->repository->insert( $offering );
+
+		return new \WP_REST_Response( [ 'id' => $id ], 201 );
+	}
+
+	public function update( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
+		$id       = absint( $request->get_param( 'id' ) );
+		$existing = $this->repository->findById( $id );
+
+		if ( null === $existing ) {
+			return new \WP_Error( 'not_found', __( 'Offering not found.', 'unsupervised-schedular' ), [ 'status' => 404 ] );
+		}
+
+		if ( ! $this->ownsOrManagesAll( $existing ) ) {
+			return new \WP_Error( 'forbidden', __( 'You cannot edit this offering.', 'unsupervised-schedular' ), [ 'status' => 403 ] );
+		}
+
+		$kind = $request->has_param( 'kind' ) ? (string) $request->get_param( 'kind' ) : $existing->kind;
+		if ( ! in_array( $kind, Offering::VALID_KINDS, true ) ) {
+			return $this->invalid( __( 'Invalid offering kind.', 'unsupervised-schedular' ) );
+		}
+
+		$billingMode = $request->has_param( 'billing_mode' ) ? (string) $request->get_param( 'billing_mode' ) : $existing->billingMode;
+		if ( ! in_array( $billingMode, Offering::VALID_BILLING_MODES, true ) ) {
+			return $this->invalid( __( 'Invalid billing mode.', 'unsupervised-schedular' ) );
+		}
+
+		$offering = new Offering(
+			instructorId:    $existing->instructorId,
+			kind:            $kind,
+			title:           $request->has_param( 'title' ) ? sanitize_text_field( (string) $request->get_param( 'title' ) ) : $existing->title,
+			priceCents:      $request->has_param( 'price_cents' ) ? absint( $request->get_param( 'price_cents' ) ) : $existing->priceCents,
+			currency:        $request->has_param( 'currency' ) ? sanitize_text_field( (string) $request->get_param( 'currency' ) ) : $existing->currency,
+			billingMode:     $billingMode,
+			description:     $request->has_param( 'description' ) ? $this->nullableText( $request->get_param( 'description' ) ) : $existing->description,
+			durationMinutes: $request->has_param( 'duration_minutes' ) ? $this->nullableInt( $request->get_param( 'duration_minutes' ) ) : $existing->durationMinutes,
+			allowWeekly:     $request->has_param( 'allow_weekly' ) ? (bool) $request->get_param( 'allow_weekly' ) : $existing->allowWeekly,
+			capacity:        $request->has_param( 'capacity' ) ? $this->nullableInt( $request->get_param( 'capacity' ) ) : $existing->capacity,
+			termStart:       $request->has_param( 'term_start' ) ? $this->nullableText( $request->get_param( 'term_start' ) ) : $existing->termStart,
+			termEnd:         $request->has_param( 'term_end' ) ? $this->nullableText( $request->get_param( 'term_end' ) ) : $existing->termEnd,
+			scheduleNote:    $request->has_param( 'schedule_note' ) ? $this->nullableText( $request->get_param( 'schedule_note' ) ) : $existing->scheduleNote,
+			isActive:        $request->has_param( 'is_active' ) ? (bool) $request->get_param( 'is_active' ) : $existing->isActive,
+			id:              $id,
+		);
+
+		$this->repository->update( $id, $offering );
+
+		return new \WP_REST_Response( $offering->toArray(), 200 );
+	}
+
+	public function delete( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
+		$id       = absint( $request->get_param( 'id' ) );
+		$existing = $this->repository->findById( $id );
+
+		if ( null === $existing ) {
+			return new \WP_Error( 'not_found', __( 'Offering not found.', 'unsupervised-schedular' ), [ 'status' => 404 ] );
+		}
+
+		if ( ! $this->ownsOrManagesAll( $existing ) ) {
+			return new \WP_Error( 'forbidden', __( 'You cannot delete this offering.', 'unsupervised-schedular' ), [ 'status' => 403 ] );
+		}
+
+		$this->repository->delete( $id );
+
+		return new \WP_REST_Response( null, 204 );
+	}
+
+	public function canManage(): bool {
+		return is_user_logged_in() && current_user_can( RoleManager::CAP_MANAGE_OFFERINGS );
+	}
+
+	/**
+	 * An offering may be changed by its owning instructor or by a studio admin
+	 * (identified by the studio-only manage_instructors capability).
+	 */
+	private function ownsOrManagesAll( Offering $offering ): bool {
+		return get_current_user_id() === $offering->instructorId
+			|| current_user_can( RoleManager::CAP_MANAGE_INSTRUCTORS );
+	}
+
+	private function invalid( string $message ): \WP_Error {
+		return new \WP_Error( 'invalid_offering', $message, [ 'status' => 400 ] );
+	}
+
+	private function nullableInt( mixed $value ): ?int {
+		return ( null === $value || '' === $value ) ? null : (int) $value;
+	}
+
+	private function nullableText( mixed $value ): ?string {
+		if ( null === $value || '' === $value ) {
+			return null;
+		}
+
+		return sanitize_text_field( (string) $value );
+	}
+}