unsupervised-scheduler/tests/Unit/Booking/BookingEndpointTest.php

<?php
declare(strict_types=1);

namespace Unsupervised\Schedular\Tests\Unit\Booking;

use Brain\Monkey\Functions;
use Mockery;
use Unsupervised\Schedular\Availability\AvailabilityRepository;
use Unsupervised\Schedular\Availability\AvailabilitySlot;
use Unsupervised\Schedular\Booking\BookingEndpoint;
use Unsupervised\Schedular\Booking\BookingRepository;
use Unsupervised\Schedular\Booking\CancellationPolicy;
use Unsupervised\Schedular\Booking\Lesson;
use Unsupervised\Schedular\Booking\LessonBooker;
use Unsupervised\Schedular\GroupClass\SessionSchedule;
use Unsupervised\Schedular\Guardian\GuardianService;
use Unsupervised\Schedular\Offering\Offering;
use Unsupervised\Schedular\Offering\OfferingRepository;
use Unsupervised\Schedular\Payment\Payment;
use Unsupervised\Schedular\Payment\PaymentService;
use Unsupervised\Schedular\Payment\StudioSettings;
use Unsupervised\Schedular\Policy\PolicyAcceptance;
use Unsupervised\Schedular\Registration\RegistrationGate;
use Unsupervised\Schedular\Tests\Unit\TestCase;

class BookingEndpointTest extends TestCase
{
    private GuardianService&Mockery\MockInterface $guardians;
    private AvailabilityRepository $availability;
    private BookingRepository $bookings;
    private OfferingRepository $offerings;
    private RegistrationGate $gate;
    private PaymentService $payments;
    private StudioSettings $settings;
    private SessionSchedule&Mockery\MockInterface $sessions;
    private BookingEndpoint $endpoint;

    protected function setUp(): void
    {
        parent::setUp();

        Functions\when('absint')->alias(static fn ($v): int => abs((int) $v));
        Functions\when('wp_unslash')->returnArg();
        Functions\when('sanitize_text_field')->returnArg();
        Functions\when('get_current_user_id')->justReturn(5);
        // Fixed "now" well before the fixture slot start (2026-07-01 10:00), so
        // the cancellation cutoff never trips unless a test moves it.
        Functions\when('current_time')->justReturn('2026-06-01 10:00:00');

        $this->availability = Mockery::mock(AvailabilityRepository::class);
        $this->bookings     = Mockery::mock(BookingRepository::class);
        $this->offerings    = Mockery::mock(OfferingRepository::class);
        $this->gate         = Mockery::mock(RegistrationGate::class);
        $this->payments     = Mockery::mock(PaymentService::class);
        $this->settings     = Mockery::mock(StudioSettings::class);
        $this->settings->shouldReceive('cancellationCutoffHours')->andReturn(24)->byDefault();
        // Crediting a cancelled paid lesson is exercised in dedicated tests; other
        // cancellation paths simply allow the call.
        $this->payments->shouldReceive('creditForCancelledLesson')->andReturn(null)->byDefault();

        $this->guardians = Mockery::mock(GuardianService::class);
        // The default account books only for itself: no guardian link anywhere.
        $this->guardians->shouldReceive('canActFor')
            ->andReturnUsing(static fn (int $actor, int $student): bool => $actor === $student)->byDefault();
        $this->guardians->shouldReceive('payerFor')->andReturnUsing(static fn (int $id): int => $id)->byDefault();
        $this->guardians->shouldReceive('householdIds')->andReturnUsing(static fn (int $id): array => [$id])->byDefault();
        $this->guardians->shouldReceive('studentName')->andReturn('Ada')->byDefault();

        $this->sessions = Mockery::mock(SessionSchedule::class);
        // Most tests are about one-to-one lessons; the group-class ones say so.
        $this->sessions->shouldReceive('upcomingForStudent')->andReturn([])->byDefault();
        $this->sessions->shouldReceive('upcomingForInstructor')->andReturn([])->byDefault();

        $this->endpoint = new BookingEndpoint(
            $this->availability,
            $this->bookings,
            $this->offerings,
            $this->gate,
            $this->payments,
            // The real booker over the same mocked repositories: these tests are
            // about what a booking does end to end, and the booker is where most
            // of that now lives.
            new LessonBooker($this->availability, $this->bookings, $this->offerings, $this->payments, $this->guardians),
            new CancellationPolicy($this->settings),
            $this->guardians,
            $this->sessions,
        );
    }

    private function slot(int $id, int $instructorId, ?int $offeringId, bool $isBooked = false, ?int $recurrenceGroup = null): AvailabilitySlot
    {
        return new AvailabilitySlot(
            instructorId:    $instructorId,
            startDt:         '2026-07-01 10:00:00',
            endDt:           '2026-07-01 11:00:00',
            offeringId:      $offeringId,
            isBooked:        $isBooked,
            recurrenceGroup: $recurrenceGroup,
            id:              $id,
        );
    }

    public function testBookRejectsOfferingFromAnotherInstructor(): void
    {
        // Generic slot owned by instructor 3; attacker supplies instructor 7's offering.
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(99)->andReturn(
            new Offering(instructorId: 7, kind: Offering::KIND_PRIVATE_LESSON, title: 'Cheap', price: 0.0, id: 99)
        );

        // No booking should be created.
        $this->availability->shouldNotReceive('claim');
        $this->bookings->shouldNotReceive('insert');

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 99]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('offering_mismatch', $result->get_error_code());
    }

    public function testBookRejectsOfferingThatDoesNotMatchSlotTiedOffering(): void
    {
        // Slot is tied to offering 5; attacker tries to swap in offering 99.
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, 5));
        $this->offerings->shouldNotReceive('findById');
        $this->availability->shouldNotReceive('claim');

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 99]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('offering_mismatch', $result->get_error_code());
    }

    public function testBookReturns409WhenSlotClaimFails(): void
    {
        // Generic slot; another request wins the claim first.
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 0.0, id: 8)
        );
        $this->gate->shouldReceive('validate')->andReturn(null);
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(false);
        $this->bookings->shouldNotReceive('insert');

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('slot_taken', $result->get_error_code());
    }

    public function testBookSucceedsForGenericSlotWithSameInstructorOffering(): void
    {
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 0.0, id: 8)
        );
        $this->gate->shouldReceive('validate')->andReturn(null);
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);
        $this->bookings->shouldReceive('insert')->once()->andReturn(77);
        $this->gate->shouldReceive('record')->once();
        // Free offering → no payment, so the lesson is confirmed immediately.
        $this->payments->shouldNotReceive('createForRegistration');
        $this->bookings->shouldReceive('updateStatus')->with(77, Lesson::STATUS_CONFIRMED)->once()->andReturn(true);

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(201, $result->get_status());
        self::assertSame([77], $result->get_data()['ids']);
        self::assertSame(Lesson::STATUS_CONFIRMED, $result->get_data()['status']);
        self::assertNull($result->get_data()['payment']);
    }

    public function testBookWithoutOfferingIsRejected(): void
    {
        // A booking with no offering would be silently free, so it must be refused.
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldNotReceive('findById');
        $this->availability->shouldNotReceive('claim');
        $this->bookings->shouldNotReceive('insert');

        $request = new \WP_REST_Request(['slot_id' => 10]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('offering_required', $result->get_error_code());
    }

    public function testBookUsesSlotTiedOfferingWhenRequestOmitsIt(): void
    {
        // Slot tied to offering 5: the booking must charge that offering even
        // though the client sent no offering_id.
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, 5));
        $this->offerings->shouldReceive('findById')->with(5)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 50.0, id: 5)
        );
        $this->gate->shouldReceive('validate')->andReturn(null);
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);
        $this->bookings->shouldReceive('insert')
            ->once()
            ->with(Mockery::on(static fn (Lesson $l): bool => 5 === $l->offeringId))
            ->andReturn(77);
        $this->gate->shouldReceive('record')->once();
        $this->payments->shouldReceive('createForRegistration')
            ->once()
            ->with(Payment::REG_LESSON, 77, 5, 3, 50.0, 'CAD', null, null, null, 5)
            ->andReturn(new Payment(
                studentId:        5,
                instructorId:     3,
                registrationType: Payment::REG_LESSON,
                registrationId:   77,
                amount:           50.0,
                method:           Payment::METHOD_ETRANSFER,
                status:           Payment::STATUS_PENDING,
                id:               12,
            ));
        $this->bookings->shouldNotReceive('updateStatus');

        $request = new \WP_REST_Request(['slot_id' => 10]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_PENDING, $result->get_data()['status']);
    }

    public function testBookRejectsInactiveStudentChosenOffering(): void
    {
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Retired', price: 50.0, isActive: false, id: 8)
        );
        $this->availability->shouldNotReceive('claim');

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('invalid_offering', $result->get_error_code());
    }

    public function testBookRejectsGroupClassOfferingForLessonSlot(): void
    {
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_GROUP_CLASS, title: 'Choir', price: 10.0, id: 8)
        );
        $this->availability->shouldNotReceive('claim');

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('invalid_offering', $result->get_error_code());
    }

    public function testBookRejectsOfferingWhoseDurationDoesNotFitSlot(): void
    {
        // Slot is 60 minutes (the helper default); a 30-minute offering cannot book it.
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Short', price: 25.0, durationMinutes: 30, id: 8)
        );
        $this->availability->shouldNotReceive('claim');

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('offering_mismatch', $result->get_error_code());
    }

    public function testBookWithPricedOfferingStaysPendingAndReturnsPaymentSummary(): void
    {
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 50.0, id: 8)
        );
        $this->gate->shouldReceive('validate')->andReturn(null);
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);
        $this->bookings->shouldReceive('insert')->once()->andReturn(77);
        $this->gate->shouldReceive('record')->once();
        $this->payments->shouldReceive('createForRegistration')
            ->once()
            ->with(Payment::REG_LESSON, 77, 5, 3, 50.0, 'CAD', null, null, null, 5)
            ->andReturn(new Payment(
                studentId:        5,
                instructorId:     3,
                registrationType: Payment::REG_LESSON,
                registrationId:   77,
                amount:           50.0,
                method:           Payment::METHOD_ETRANSFER,
                status:           Payment::STATUS_PENDING,
                id:               12,
            ));
        // Awaiting payment: the lesson must not be confirmed yet.
        $this->bookings->shouldNotReceive('updateStatus');

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_PENDING, $result->get_data()['status']);
        self::assertSame(
            ['id' => 12, 'method' => Payment::METHOD_ETRANSFER, 'status' => Payment::STATUS_PENDING],
            $result->get_data()['payment']
        );
    }

    public function testBookWithCompedPaymentReturnsConfirmedStatus(): void
    {
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 50.0, id: 8)
        );
        $this->gate->shouldReceive('validate')->andReturn(null);
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);
        $this->bookings->shouldReceive('insert')->once()->andReturn(77);
        $this->gate->shouldReceive('record')->once();
        // Comped students are paid on creation (PaymentService confirms the lesson itself).
        $this->payments->shouldReceive('createForRegistration')->once()->andReturn(new Payment(
            studentId:        5,
            instructorId:     3,
            registrationType: Payment::REG_LESSON,
            registrationId:   77,
            amount:           50.0,
            method:           Payment::METHOD_COMP,
            status:           Payment::STATUS_PAID,
            id:               12,
        ));
        $this->bookings->shouldNotReceive('updateStatus');

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_CONFIRMED, $result->get_data()['status']);
        self::assertSame(Payment::METHOD_COMP, $result->get_data()['payment']['method']);
    }

    public function testWeeklyBookingChargesPerLessonPriceTimesClaimedOccurrences(): void
    {
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null, false, 7));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 50.0, allowWeekly: true, id: 8)
        );
        $this->gate->shouldReceive('validate')->andReturn(null);

        $this->availability->shouldReceive('findUnbookedInGroup')->with(7)->andReturn([
            $this->slot(10, 3, null, false, 7),
            $this->slot(11, 3, null, false, 7),
            $this->slot(12, 3, null, false, 7),
        ]);
        $this->availability->shouldReceive('claim')->times(3)->andReturn(true);
        $this->bookings->shouldReceive('insertSeries')->once()->andReturn([77, 78, 79]);
        $this->gate->shouldReceive('record')->once();

        // Three claimed occurrences at a per-lesson (one_time) price of 50 → 150.
        $this->payments->shouldReceive('createForRegistration')
            ->once()
            ->with(Payment::REG_LESSON, 77, 5, 3, 150.0, 'CAD', null, null, null, 5)
            ->andReturn(new Payment(5, 3, Payment::REG_LESSON, 77, 150.0, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, id: 12));
        $this->bookings->shouldNotReceive('updateStatus');

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8, 'recurrence' => 'weekly']);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame([77, 78, 79], $result->get_data()['ids']);
        self::assertSame(Lesson::STATUS_PENDING, $result->get_data()['status']);
    }

    public function testWeeklyBookingChargesFullTermPriceOnce(): void
    {
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null, false, 7));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(
                instructorId: 3,
                kind: Offering::KIND_PRIVATE_LESSON,
                title: 'Term',
                price: 400.0,
                billingMode: Offering::BILLING_FULL_TERM,
                allowWeekly: true,
                id: 8
            )
        );
        $this->gate->shouldReceive('validate')->andReturn(null);

        $this->availability->shouldReceive('findUnbookedInGroup')->with(7)->andReturn([
            $this->slot(10, 3, null, false, 7),
            $this->slot(11, 3, null, false, 7),
        ]);
        $this->availability->shouldReceive('claim')->times(2)->andReturn(true);
        $this->bookings->shouldReceive('insertSeries')->once()->andReturn([77, 78]);
        $this->gate->shouldReceive('record')->once();

        // A full_term price already covers the whole reservation.
        $this->payments->shouldReceive('createForRegistration')
            ->once()
            ->with(Payment::REG_LESSON, 77, 5, 3, 400.0, 'CAD', null, null, null, 5)
            ->andReturn(new Payment(5, 3, Payment::REG_LESSON, 77, 400.0, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, id: 12));
        $this->bookings->shouldNotReceive('updateStatus');

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8, 'recurrence' => 'weekly']);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_PENDING, $result->get_data()['status']);
    }

    public function testScheduledBillingDefersPaymentAndConfirmsLesson(): void
    {
        // Weekly/monthly offerings are billed later by the daily scan, not at
        // booking: no payment is created now, and the reserved lesson is confirmed.
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 50.0, billingMode: Offering::BILLING_WEEKLY, id: 8)
        );
        $this->gate->shouldReceive('validate')->andReturn(null);
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);
        $this->bookings->shouldReceive('insert')->once()->andReturn(77);
        $this->gate->shouldReceive('record')->once();
        $this->payments->shouldNotReceive('createForRegistration');
        $this->bookings->shouldReceive('updateStatus')->with(77, Lesson::STATUS_CONFIRMED)->once()->andReturn(true);

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_CONFIRMED, $result->get_data()['status']);
        self::assertNull($result->get_data()['payment']);
    }

    public function testMonthlyLessonInAlreadyBilledMonthChargesAtBooking(): void
    {
        // "now" is 2026-06-01; a monthly lesson booked into June (its billing 1st
        // already reached) is an add-on and must be charged at booking, not deferred.
        $this->availability->shouldReceive('findById')->with(10)->andReturn(
            new AvailabilitySlot(instructorId: 3, startDt: '2026-06-20 10:00:00', endDt: '2026-06-20 11:00:00', offeringId: null, id: 10)
        );
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 45.0, billingMode: Offering::BILLING_MONTHLY, id: 8)
        );
        $this->gate->shouldReceive('validate')->andReturn(null);
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);
        $this->bookings->shouldReceive('insert')->once()->andReturn(77);
        $this->gate->shouldReceive('record')->once();

        // Charged now, for a single lesson's fee, as a normal (non-scheduled) payment.
        $this->payments->shouldReceive('createForRegistration')
            ->once()
            ->with(Payment::REG_LESSON, 77, 5, 3, 45.0, 'CAD', null, null, null, 5)
            ->andReturn(new Payment(5, 3, Payment::REG_LESSON, 77, 45.0, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, id: 12));
        $this->bookings->shouldNotReceive('updateStatus');

        $result = $this->endpoint->book(new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8]));

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_PENDING, $result->get_data()['status']);
        self::assertNotNull($result->get_data()['payment']);
    }

    public function testMonthlyLessonBeforeBillingDateDefersPayment(): void
    {
        // "now" is 2026-06-01; a monthly lesson for July is booked before July's 1st,
        // so it defers to the daily scan (no payment now, lesson confirmed).
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 45.0, billingMode: Offering::BILLING_MONTHLY, id: 8)
        );
        $this->gate->shouldReceive('validate')->andReturn(null);
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);
        $this->bookings->shouldReceive('insert')->once()->andReturn(77);
        $this->gate->shouldReceive('record')->once();
        $this->payments->shouldNotReceive('createForRegistration');
        $this->bookings->shouldReceive('updateStatus')->with(77, Lesson::STATUS_CONFIRMED)->once()->andReturn(true);

        $result = $this->endpoint->book(new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8]));

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_CONFIRMED, $result->get_data()['status']);
        self::assertNull($result->get_data()['payment']);
    }

    public function testCancelByOwnerCancelsReleasesSlotAndVoidsPayment(): void
    {
        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, status: Lesson::STATUS_PENDING, paymentId: 12, id: 77);
        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->bookings->shouldReceive('updateStatus')->with(77, Lesson::STATUS_CANCELLED)->once()->andReturn(true);
        $this->availability->shouldReceive('release')->with(10)->once()->andReturn(true);
        $this->payments->shouldReceive('voidPending')->with(12)->once();

        $result = $this->endpoint->cancel(new \WP_REST_Request(['id' => 77]));

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_CANCELLED, $result->get_data()['status']);
    }

    public function testCancelCreditsThePaidLesson(): void
    {
        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, status: Lesson::STATUS_PENDING, paymentId: 12, id: 77);
        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->bookings->shouldReceive('updateStatus')->with(77, Lesson::STATUS_CANCELLED)->once()->andReturn(true);
        $this->availability->shouldReceive('release')->with(10)->once()->andReturn(true);
        $this->payments->shouldReceive('voidPending')->with(12)->once();

        // The cancelled lesson (the value object, so its payment_id is intact) is
        // handed to the credit path.
        $this->payments->shouldReceive('creditForCancelledLesson')
            ->once()
            ->with(Mockery::on(static fn (Lesson $l): bool => $l->id === 77 && $l->paymentId === 12));

        $this->endpoint->cancel(new \WP_REST_Request(['id' => 77]));
    }

    public function testCancelWithinStudioCutoffIsRejected(): void
    {
        // Now (2026-06-01 10:00) is only 24h before a slot at 2026-06-02 10:00,
        // exactly the studio cutoff — inside the window, so cancellation closes.
        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, status: Lesson::STATUS_PENDING, paymentId: 12, id: 77);
        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
        $this->availability->shouldReceive('findById')->with(10)->andReturn(new AvailabilitySlot(
            instructorId: 3,
            startDt:      '2026-06-02 09:59:00',
            endDt:        '2026-06-02 10:59:00',
            id:           10,
        ));
        $this->bookings->shouldNotReceive('updateStatus');
        $this->availability->shouldNotReceive('release');
        $this->payments->shouldNotReceive('voidPending');

        $result = $this->endpoint->cancel(new \WP_REST_Request(['id' => 77]));

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('cancellation_closed', $result->get_error_code());
    }

    public function testCancelUsesOfferingCutoffOverrideWhenSet(): void
    {
        // Offering overrides the 24h studio default with 0 hours — cancel any time,
        // even for a lesson starting in a minute.
        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, offeringId: 4, status: Lesson::STATUS_PENDING, paymentId: 12, id: 77);
        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
        $this->availability->shouldReceive('findById')->with(10)->andReturn(new AvailabilitySlot(
            instructorId: 3,
            startDt:      '2026-06-01 10:01:00',
            endDt:        '2026-06-01 11:01:00',
            id:           10,
        ));
        $this->offerings->shouldReceive('findById')->with(4)->andReturn(new Offering(
            instructorId: 3,
            kind:         Offering::KIND_PRIVATE_LESSON,
            title:        'Trial',
            cancellationCutoffHours: 0,
        ));
        $this->bookings->shouldReceive('updateStatus')->with(77, Lesson::STATUS_CANCELLED)->once()->andReturn(true);
        $this->availability->shouldReceive('release')->with(10)->once()->andReturn(true);
        $this->payments->shouldReceive('voidPending')->with(12)->once();

        $result = $this->endpoint->cancel(new \WP_REST_Request(['id' => 77]));

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_CANCELLED, $result->get_data()['status']);
    }

    public function testCancelByAnotherStudentAnswersExactlyLikeAnUnknownLesson(): void
    {
        // Lesson belongs to student 9; current user is 5. The refusal must be
        // indistinguishable from testCancelUnknownLessonReturns404 below, or the
        // pair of answers tells a student which lesson ids exist.
        $lesson = new Lesson(slotId: 10, studentId: 9, instructorId: 3, status: Lesson::STATUS_PENDING, id: 77);
        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
        $this->bookings->shouldNotReceive('updateStatus');
        $this->availability->shouldNotReceive('release');

        $result = $this->endpoint->cancel(new \WP_REST_Request(['id' => 77]));

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('not_found', $result->get_error_code());
        self::assertSame(404, $result->error_data['not_found']['status']);
    }

    public function testCancelUnknownLessonReturns404(): void
    {
        $this->bookings->shouldReceive('findById')->with(99)->andReturn(null);

        $result = $this->endpoint->cancel(new \WP_REST_Request(['id' => 99]));

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('not_found', $result->get_error_code());
        self::assertSame(404, $result->error_data['not_found']['status']);
    }

    public function testCancelAlreadyCancelledLessonIsIdempotent(): void
    {
        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, status: Lesson::STATUS_CANCELLED, id: 77);
        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
        $this->bookings->shouldNotReceive('updateStatus');
        $this->availability->shouldNotReceive('release');
        $this->payments->shouldNotReceive('voidPending');

        $result = $this->endpoint->cancel(new \WP_REST_Request(['id' => 77]));

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_CANCELLED, $result->get_data()['status']);
    }

    public function testUpdateStatusToCancelledReleasesSlotAndVoidsPayment(): void
    {
        // Current user 5 is the lesson's instructor.
        $lesson = new Lesson(slotId: 10, studentId: 9, instructorId: 5, status: Lesson::STATUS_PENDING, paymentId: 12, id: 77);
        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
        $this->availability->shouldReceive('release')->with(10)->once()->andReturn(true);
        $this->payments->shouldReceive('voidPending')->with(12)->once();
        $this->bookings->shouldReceive('updateStatus')->with(77, Lesson::STATUS_CANCELLED)->once()->andReturn(true);

        $result = $this->endpoint->updateStatus(new \WP_REST_Request(['id' => 77, 'status' => Lesson::STATUS_CANCELLED]));

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_CANCELLED, $result->get_data()['status']);
    }

    public function testUpdateStatusReinstatingCancelledLessonReclaimsSlot(): void
    {
        $lesson = new Lesson(slotId: 10, studentId: 9, instructorId: 5, status: Lesson::STATUS_CANCELLED, id: 77);
        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);
        $this->bookings->shouldReceive('updateStatus')->with(77, Lesson::STATUS_CONFIRMED)->once()->andReturn(true);

        $result = $this->endpoint->updateStatus(new \WP_REST_Request(['id' => 77, 'status' => Lesson::STATUS_CONFIRMED]));

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(Lesson::STATUS_CONFIRMED, $result->get_data()['status']);
    }

    public function testUpdateStatusReinstatingFailsWhenSlotRebooked(): void
    {
        $lesson = new Lesson(slotId: 10, studentId: 9, instructorId: 5, status: Lesson::STATUS_CANCELLED, id: 77);
        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
        // Someone booked the freed time in the meantime.
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(false);
        $this->bookings->shouldNotReceive('updateStatus');

        $result = $this->endpoint->updateStatus(new \WP_REST_Request(['id' => 77, 'status' => Lesson::STATUS_CONFIRMED]));

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('slot_taken', $result->get_error_code());
    }

    public function testMyLessonsForStudentIncludesSlotTimes(): void
    {
        Functions\when('current_user_can')->justReturn(false);

        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, status: Lesson::STATUS_PENDING, id: 77);
        $this->bookings->shouldReceive('findUpcomingForStudent')->with(5)->once()->andReturn([$lesson]);
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));

        $result = $this->endpoint->myLessons(new \WP_REST_Request([]));

        $data = $result->get_data();
        self::assertCount(1, $data);
        self::assertSame(77, $data[0]['id']);
        self::assertSame('2026-07-01 10:00:00', $data[0]['start_dt']);
        self::assertSame('2026-07-01 11:00:00', $data[0]['end_dt']);
    }

    public function testMyLessonsIncludesBookedOfferingName(): void
    {
        Functions\when('current_user_can')->justReturn(false);

        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, offeringId: 8, status: Lesson::STATUS_PENDING, id: 77);
        $this->bookings->shouldReceive('findUpcomingForStudent')->with(5)->once()->andReturn([$lesson]);
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, 8));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Piano Lesson', durationMinutes: 60, id: 8)
        );

        $result = $this->endpoint->myLessons(new \WP_REST_Request([]));

        $data = $result->get_data();
        self::assertSame('Piano Lesson', $data[0]['offering_title']);
        self::assertSame(60, $data[0]['duration_minutes']);
    }

    /**
     * The authorisation boundary of guardian booking: without it any signed-in
     * student could book — and bill — against any user id they cared to send.
     */
    public function testBookForAStudentTheCallerDoesNotGuardIsForbidden(): void
    {
        $this->guardians->shouldReceive('canActFor')->with(5, 99)->andReturn(false);

        // Rejected before anything is looked up, claimed, or charged.
        $this->availability->shouldNotReceive('findById');
        $this->availability->shouldNotReceive('claim');
        $this->bookings->shouldNotReceive('insert');
        $this->payments->shouldNotReceive('createForRegistration');

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8, 'student_id' => 99]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_Error::class, $result);
        self::assertSame('forbidden', $result->get_error_code());
    }

    public function testGuardianBooksTheLessonInTheChildsNameAndBillsThemselves(): void
    {
        $this->guardians->shouldReceive('canActFor')->with(5, 42)->andReturn(true);
        $this->guardians->shouldReceive('payerFor')->with(42)->andReturn(5);

        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 50.0, id: 8)
        );
        $this->gate->shouldReceive('validate')->andReturn(null);
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);

        // The lesson belongs to the child…
        $this->bookings->shouldReceive('insert')
            ->once()
            ->with(Mockery::on(static fn (Lesson $l): bool => $l->studentId === 42))
            ->andReturn(77);

        // …the acceptance names the child but is attributed to the guardian…
        $this->gate->shouldReceive('record')
            ->once()
            ->with(PolicyAcceptance::REG_LESSON, 77, 42, 8, Mockery::any(), Mockery::any(), Mockery::any(), 5);

        // …and the charge is raised against the child but owed by the guardian.
        $this->payments->shouldReceive('createForRegistration')
            ->once()
            ->with(Payment::REG_LESSON, 77, 42, 3, 50.0, 'CAD', null, null, null, 5)
            ->andReturn(new Payment(42, 3, Payment::REG_LESSON, 77, 50.0, payerId: 5, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, id: 12));

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8, 'student_id' => 42]);
        $result  = $this->endpoint->book($request);

        self::assertInstanceOf(\WP_REST_Response::class, $result);
        self::assertSame(201, $result->get_status());
    }

    /**
     * Sending your own id explicitly is the same as sending none — no guardian
     * lookup is needed to book for yourself.
     */
    public function testBookForYourOwnIdNeedsNoGuardianLink(): void
    {
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 0.0, id: 8)
        );
        $this->gate->shouldReceive('validate')->andReturn(null);
        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);
        $this->bookings->shouldReceive('insert')
            ->once()
            ->with(Mockery::on(static fn (Lesson $l): bool => $l->studentId === 5))
            ->andReturn(77);
        $this->gate->shouldReceive('record')->once();
        $this->bookings->shouldReceive('updateStatus')->once()->andReturn(true);

        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8, 'student_id' => 5]);

        self::assertInstanceOf(\WP_REST_Response::class, $this->endpoint->book($request));
    }

    public function testGuardianMayCancelTheirChildsLesson(): void
    {
        $this->guardians->shouldReceive('canActFor')->with(5, 42)->andReturn(true);

        $lesson = new Lesson(slotId: 10, studentId: 42, instructorId: 3, status: Lesson::STATUS_CONFIRMED, id: 77);
        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->bookings->shouldReceive('updateStatus')->once()->with(77, Lesson::STATUS_CANCELLED)->andReturn(true);
        $this->availability->shouldReceive('release')->once()->with(10)->andReturn(true);
        $this->payments->shouldReceive('voidPending')->once();

        $result = $this->endpoint->cancel(new \WP_REST_Request(['id' => 77]));

        self::assertInstanceOf(\WP_REST_Response::class, $result);
    }

    public function testMyLessonsCoversTheWholeHouseholdSortedByStart(): void
    {
        Functions\when('current_user_can')->justReturn(false);

        $this->guardians->shouldReceive('householdIds')->with(5)->andReturn([5, 42]);
        $this->guardians->shouldReceive('studentName')->with(5)->andReturn('Grace');
        $this->guardians->shouldReceive('studentName')->with(42)->andReturn('Ada');

        $mine  = new Lesson(slotId: 11, studentId: 5, instructorId: 3, status: Lesson::STATUS_CONFIRMED, id: 78);
        $childs = new Lesson(slotId: 10, studentId: 42, instructorId: 3, status: Lesson::STATUS_CONFIRMED, id: 77);

        $this->bookings->shouldReceive('findUpcomingForStudent')->with(5)->andReturn([$mine]);
        $this->bookings->shouldReceive('findUpcomingForStudent')->with(42)->andReturn([$childs]);

        // Slot 10 starts first, so the child's lesson leads the merged list.
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
        $this->availability->shouldReceive('findById')->with(11)->andReturn(new AvailabilitySlot(
            instructorId:    3,
            startDt:         '2026-07-02 10:00:00',
            endDt:           '2026-07-02 11:00:00',
            durationMinutes: 60,
            id:              11,
        ));

        $data = $this->endpoint->myLessons(new \WP_REST_Request([]))->get_data();

        self::assertSame([77, 78], array_column($data, 'id'));
        self::assertSame(['Ada', 'Grace'], array_column($data, 'student_name'));
    }

    /**
     * A group class has no availability slot behind it, so it never appeared in
     * this list at all — a student whose whole term was a group class saw an
     * empty schedule. Its sessions now sort in among the booked lessons.
     */
    public function testMyLessonsInterleavesGroupClassSessionsWithLessons(): void
    {
        Functions\when('current_user_can')->justReturn(false);

        $this->guardians->shouldReceive('householdIds')->with(5)->andReturn([5]);
        $this->guardians->shouldReceive('studentName')->with(5)->andReturn('Grace');

        // Slot 10 starts 2026-07-01 10:00 (the fixture), so the class on
        // 2026-06-30 comes first and the one on 2026-07-07 last.
        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, status: Lesson::STATUS_CONFIRMED, id: 78);
        $this->bookings->shouldReceive('findUpcomingForStudent')->with(5)->andReturn([$lesson]);
        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));

        $this->sessions->shouldReceive('upcomingForStudent')->with(5, '2026-06-01 10:00:00')->andReturn([
            [
                'enrollment_id'    => 40,
                'offering_id'      => 8,
                'offering_title'   => 'Choir',
                'instructor_id'    => 3,
                'status'           => 'active',
                'start_dt'         => '2026-06-30 16:00:00',
                'end_dt'           => '2026-06-30 17:00:00',
                'duration_minutes' => 60,
            ],
            [
                'enrollment_id'    => 40,
                'offering_id'      => 8,
                'offering_title'   => 'Choir',
                'instructor_id'    => 3,
                'status'           => 'active',
                'start_dt'         => '2026-07-07 16:00:00',
                'end_dt'           => '2026-07-07 17:00:00',
                'duration_minutes' => 60,
            ],
        ]);

        $data = $this->endpoint->myLessons(new \WP_REST_Request([]))->get_data();

        self::assertSame(
            ['2026-06-30 16:00:00', '2026-07-01 10:00:00', '2026-07-07 16:00:00'],
            array_column($data, 'start_dt')
        );

        // `kind` is what lets the panel withhold a Cancel button from a session
        // that is a date in a term rather than a booked slot. A lesson carries no
        // `kind` at all, which is the absence the panel reads as "cancellable".
        self::assertSame('group_class', $data[0]['kind']);
        self::assertSame('group_class', $data[2]['kind']);
        self::assertSame('Choir', $data[0]['offering_title']);
        self::assertSame('Grace', $data[0]['student_name']);
        self::assertArrayNotHasKey('kind', $data[1]);
    }

    /**
     * An instructor's own group classes join their schedule the same way, and
     * one session is one row however many students are enrolled in it.
     */
    public function testMyLessonsAddsAnInstructorsOwnGroupClassSessions(): void
    {
        Functions\when('current_user_can')->justReturn(true);

        $this->bookings->shouldReceive('findUpcomingForInstructor')->with(5)->andReturn([]);
        $this->sessions->shouldReceive('upcomingForInstructor')->with(5, '2026-06-01 10:00:00')->andReturn([
            [
                'enrollment_id'    => 0,
                'offering_id'      => 8,
                'offering_title'   => 'Choir',
                'instructor_id'    => 5,
                'status'           => 'active',
                'start_dt'         => '2026-06-30 16:00:00',
                'end_dt'           => '2026-06-30 17:00:00',
                'duration_minutes' => 60,
            ],
        ]);

        $data = $this->endpoint->myLessons(new \WP_REST_Request([]))->get_data();

        self::assertCount(1, $data);
        self::assertSame('group_class', $data[0]['kind']);
        self::assertSame('Choir', $data[0]['offering_title']);
        // Nobody's name: the row is the class, not one student's place in it.
        self::assertArrayNotHasKey('student_name', $data[0]);
    }
}