Add cancellation cutoff limiting how close to a lesson a student can cancel

Students can no longer cancel their own lesson online once it starts within a
configured window; instructors and studio admins can always cancel.

- Studio default `us_cancellation_cutoff_hours` (stored/computed in hours,
  entered and displayed in days under Studio Settings → Cancellations).
- Optional per-offering override `cancellation_cutoff_hours` (entered in hours);
  blank inherits the studio default, 0 allows anytime cancellation.
- `Booking\CancellationPolicy` resolves the effective window and decides;
  `BookingEndpoint::cancel()` returns a 403 `cancellation_closed` when too late.
  The instructor status endpoint and studio-admin student actions bypass it.

Closes #93

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

tests/Unit/Booking/BookingEndpointTest.php

@@ -9,11 +9,13 @@ 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\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\Registration\RegistrationGate;
 use Unsupervised\Schedular\Tests\Unit\TestCase;
 
@@ -24,6 +26,7 @@ class BookingEndpointTest extends TestCase
     private OfferingRepository $offerings;
     private RegistrationGate $gate;
     private PaymentService $payments;
+    private StudioSettings $settings;
     private BookingEndpoint $endpoint;
 
     protected function setUp(): void
@@ -34,12 +37,17 @@ class BookingEndpointTest extends TestCase
         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();
 
         $this->endpoint = new BookingEndpoint(
             $this->availability,
@@ -47,6 +55,7 @@ class BookingEndpointTest extends TestCase
             $this->offerings,
             $this->gate,
             $this->payments,
+            new CancellationPolicy($this->settings),
         );
     }
 
@@ -378,6 +387,57 @@ class BookingEndpointTest extends TestCase
     {
         $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 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();

tests/Unit/Booking/CancellationPolicyTest.php

@@ -0,0 +1,100 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Booking;
+
+use Mockery;
+use Unsupervised\Schedular\Booking\CancellationPolicy;
+use Unsupervised\Schedular\Payment\StudioSettings;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class CancellationPolicyTest extends TestCase
+{
+    private function policy(int $studioDefaultHours): CancellationPolicy
+    {
+        $settings = Mockery::mock(StudioSettings::class);
+        $settings->shouldReceive('cancellationCutoffHours')->andReturn($studioDefaultHours);
+
+        return new CancellationPolicy($settings);
+    }
+
+    public function testCutoffHoursFallsBackToStudioDefaultWhenOverrideNull(): void
+    {
+        self::assertSame(24, $this->policy(24)->cutoffHours(null));
+    }
+
+    public function testCutoffHoursUsesOverrideWhenSet(): void
+    {
+        // Even a zero override wins over the studio default — it is a deliberate
+        // "cancel any time" choice, not an absent value.
+        self::assertSame(0, $this->policy(24)->cutoffHours(0));
+        self::assertSame(72, $this->policy(24)->cutoffHours(72));
+    }
+
+    public function testCutoffHoursIgnoresNegativeOverride(): void
+    {
+        self::assertSame(24, $this->policy(24)->cutoffHours(-5));
+    }
+
+    public function testStudentMayCancelWhenOutsideWindow(): void
+    {
+        // 48h before a 24h cutoff — comfortably outside.
+        self::assertTrue(
+            $this->policy(24)->studentMayCancel('2026-07-03 10:00:00', null, '2026-07-01 10:00:00')
+        );
+    }
+
+    public function testStudentMayNotCancelWhenInsideWindow(): void
+    {
+        // 12h before a 24h cutoff — inside the window.
+        self::assertFalse(
+            $this->policy(24)->studentMayCancel('2026-07-01 22:00:00', null, '2026-07-01 10:00:00')
+        );
+    }
+
+    public function testExactlyAtCutoffBoundaryIsAllowed(): void
+    {
+        // Exactly 24h ahead of a 24h cutoff is still cancellable.
+        self::assertTrue(
+            $this->policy(24)->studentMayCancel('2026-07-02 10:00:00', null, '2026-07-01 10:00:00')
+        );
+    }
+
+    public function testZeroCutoffAlwaysAllowsCancellation(): void
+    {
+        self::assertTrue(
+            $this->policy(0)->studentMayCancel('2026-07-01 10:00:01', null, '2026-07-01 10:00:00')
+        );
+    }
+
+    public function testOfferingOverrideNarrowsWindow(): void
+    {
+        // Studio default is 0 (any time), but this offering demands 48h notice.
+        self::assertFalse(
+            $this->policy(0)->studentMayCancel('2026-07-02 10:00:00', 48, '2026-07-01 10:00:00')
+        );
+    }
+
+    public function testPastLessonCannotBeCancelled(): void
+    {
+        self::assertFalse(
+            $this->policy(24)->studentMayCancel('2026-07-01 09:00:00', null, '2026-07-01 10:00:00')
+        );
+    }
+
+    public function testDescribeCutoffUsesDaysForWholeDays(): void
+    {
+        $policy = $this->policy(24);
+
+        self::assertSame('1 day', $policy->describeCutoff(24));
+        self::assertSame('2 days', $policy->describeCutoff(48));
+    }
+
+    public function testDescribeCutoffUsesHoursOtherwise(): void
+    {
+        $policy = $this->policy(24);
+
+        self::assertSame('12 hours', $policy->describeCutoff(12));
+        self::assertSame('1 hour', $policy->describeCutoff(1));
+    }
+}