Fix API documentation and request handling mismatches

config/cachet.php

@@ -3,6 +3,7 @@
 use App\Models\User;
 use Cachet\Http\Middleware\AuthenticateApiIfProtected;
 use Cachet\Http\Middleware\EnsureApiIsEnabled;
+use Cachet\Http\Middleware\ForceJsonResponse;
 use Illuminate\Routing\Middleware\SubstituteBindings;
 
 return [
@@ -91,6 +92,7 @@
      |
      */
     'api_middleware' => [
+        ForceJsonResponse::class,
         EnsureApiIsEnabled::class,
         AuthenticateApiIfProtected::class,
         SubstituteBindings::class,

src/Data/Casts/FlexibleDateTimeCast.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Cachet\Data\Casts;
+
+use Carbon\Carbon;
+use Carbon\Exceptions\InvalidFormatException;
+use DateTimeInterface;
+use Spatie\LaravelData\Casts\Cast;
+use Spatie\LaravelData\Casts\Uncastable;
+use Spatie\LaravelData\Support\Creation\CreationContext;
+use Spatie\LaravelData\Support\DataProperty;
+
+/**
+ * Casts any date value accepted by the "date" validation rule, such as
+ * "2023-11-07 05:31:56" or ISO 8601 ("2023-11-07T05:31:56Z"), to Carbon.
+ */
+final class FlexibleDateTimeCast implements Cast
+{
+    public function cast(DataProperty $property, mixed $value, array $properties, CreationContext $context): DateTimeInterface|Uncastable
+    {
+        if ($value instanceof DateTimeInterface) {
+            return Carbon::instance($value);
+        }
+
+        if (! is_string($value) && ! is_int($value) && ! is_float($value)) {
+            return Uncastable::create();
+        }
+
+        try {
+            return Carbon::parse($value);
+        } catch (InvalidFormatException) {
+            return Uncastable::create();
+        }
+    }
+}

src/Data/Requests/Component/CreateComponentRequestData.php

@@ -31,25 +31,14 @@ public static function rules(ValidationContext $context): array
             'order' => ['int', 'min:0'],
             'enabled' => ['boolean'],
             'component_group_id' => ['int', 'min:0', Rule::exists('component_groups', 'id')],
+            /**
+             * Key/value metadata to store against the resource.
+             *
+             * @var array<string, mixed>|null
+             *
+             * @example {"cluster": "eu-west"}
+             */
             'meta' => ['nullable', 'array'],
         ];
     }
-
-    /**
-     * Specify body parameter documentation for Scribe.
-     */
-    public function bodyParameters(): array
-    {
-        return [
-            'status' => [
-                'description' => 'The status of the component. See [Component Statuses](/v3.x/guide/components#component-statuses) for more information.',
-                'example' => '1',
-                'required' => false,
-                'schema' => [
-                    'type' => 'integer',
-                    'enum' => ComponentStatusEnum::cases(),
-                ],
-            ],
-        ];
-    }
 }

src/Data/Requests/Component/UpdateComponentRequestData.php

@@ -31,6 +31,13 @@ public static function rules(ValidationContext $context): array
             'order' => ['int', 'min:0'],
             'component_group_id' => ['int', 'min:0', Rule::exists('component_groups', 'id')],
             'enabled' => ['boolean'],
+            /**
+             * Key/value metadata to store against the resource.
+             *
+             * @var array<string, mixed>|null
+             *
+             * @example {"cluster": "eu-west"}
+             */
             'meta' => ['nullable', 'array'],
         ];
     }

src/Data/Requests/ComponentGroup/CreateComponentGroupRequestData.php

@@ -43,22 +43,14 @@ public static function rules(ValidationContext $context): array
             ],
             'components' => ['array'],
             'components.*' => ['int', 'min:0', Rule::exists('components', 'id')],
+            /**
+             * Key/value metadata to store against the resource.
+             *
+             * @var array<string, mixed>|null
+             *
+             * @example {"cluster": "eu-west"}
+             */
             'meta' => ['nullable', 'array'],
         ];
     }
-
-    public function bodyParameters(): array
-    {
-        return [
-            'collapsed' => [
-                'description' => 'The collapsed state of the component group on the status page.',
-                'example' => '0',
-                'required' => false,
-                'schema' => [
-                    'type' => 'integer',
-                    'enum' => ComponentGroupVisibilityEnum::cases(),
-                ],
-            ],
-        ];
-    }
 }

src/Data/Requests/ComponentGroup/UpdateComponentGroupRequestData.php

@@ -42,22 +42,14 @@ public static function rules(ValidationContext $context): array
             ],
             'components' => ['array'],
             'components.*' => ['int', 'min:0', Rule::exists('components', 'id')],
+            /**
+             * Key/value metadata to store against the resource.
+             *
+             * @var array<string, mixed>|null
+             *
+             * @example {"cluster": "eu-west"}
+             */
             'meta' => ['nullable', 'array'],
         ];
     }
-
-    public function bodyParameters(): array
-    {
-        return [
-            'collapsed' => [
-                'description' => 'The collapsed state of the component group on the status page.',
-                'example' => '0',
-                'required' => false,
-                'schema' => [
-                    'type' => 'integer',
-                    'enum' => ComponentGroupVisibilityEnum::cases(),
-                ],
-            ],
-        ];
-    }
 }

src/Data/Requests/Incident/CreateIncidentRequestData.php

@@ -50,13 +50,30 @@ public static function rules(ValidationContext $context): array
             'visible' => ['boolean'],
             'stickied' => ['boolean'],
             'notifications' => ['boolean'],
+            /**
+             * The date/time the incident occurred, e.g. "2023-11-07 05:31:56" or ISO 8601. Defaults to now.
+             */
             'occurred_at' => ['nullable', 'date'],
+            /**
+             * Key/value variables passed to the incident template when rendering the message.
+             *
+             * @var array<string, mixed>
+             *
+             * @example {"reason": "scheduled maintenance"}
+             */
             'template_vars' => ['array'],
             'component_id' => [Rule::exists('components', 'id')],
             'component_status' => ['nullable', Rule::enum(ComponentStatusEnum::class), 'required_with:component_id'],
             'components' => ['array'],
-            'components.*.id' => ['required_with:components', 'int', 'exists:components,id'],
-            'components.*.status' => ['required_with:components', 'int', Rule::enum(ComponentStatusEnum::class)],
+            'components.*.id' => ['required', 'int', 'exists:components,id'],
+            'components.*.status' => ['required', 'int', Rule::enum(ComponentStatusEnum::class)],
+            /**
+             * Key/value metadata to store against the resource.
+             *
+             * @var array<string, mixed>|null
+             *
+             * @example {"cluster": "eu-west"}
+             */
             'meta' => ['nullable', 'array'],
         ];
     }

src/Data/Requests/Incident/UpdateIncidentRequestData.php

@@ -31,7 +31,17 @@ public static function rules(ValidationContext $context): array
             'visible' => ['boolean'],
             'stickied' => ['boolean'],
             'notifications' => ['boolean'],
+            /**
+             * The date/time the incident occurred, e.g. "2023-11-07 05:31:56" or ISO 8601.
+             */
             'occurred_at' => ['nullable', 'date'],
+            /**
+             * Key/value metadata to store against the resource.
+             *
+             * @var array<string, mixed>|null
+             *
+             * @example {"cluster": "eu-west"}
+             */
             'meta' => ['nullable', 'array'],
         ];
     }

src/Data/Requests/Metric/CreateMetricPointRequestData.php

@@ -17,6 +17,11 @@ public static function rules(ValidationContext $context): array
     {
         return [
             'value' => ['required', 'numeric'],
+            /**
+             * The date/time or Unix timestamp the metric point was recorded at. Defaults to now.
+             *
+             * @example "2023-11-07 05:31:56"
+             */
             'timestamp' => ['nullable', new ValidTimestamp],
         ];
     }

src/Data/Requests/Metric/CreateMetricRequestData.php

@@ -5,6 +5,7 @@
 use Cachet\Data\BaseData;
 use Cachet\Enums\MetricTypeEnum;
 use Cachet\Rules\FactorOfSixty;
+use Illuminate\Validation\Rule;
 use Spatie\LaravelData\Support\Validation\ValidationContext;
 
 final class CreateMetricRequestData extends BaseData
@@ -25,9 +26,12 @@ public static function rules(ValidationContext $context): array
         return [
             'name' => ['required', 'string', 'max:255'],
             'suffix' => ['required', 'string', 'max:255'],
+            'calc_type' => ['nullable', Rule::enum(MetricTypeEnum::class)],
             'description' => ['string'],
             'default_value' => ['decimal:1,2'],
+            'display_chart' => ['nullable', 'boolean'],
             'threshold' => ['int', 'min:0', 'max:60', new FactorOfSixty],
+            'places' => ['int', 'min:0', 'max:4'],
         ];
     }
 }

src/Data/Requests/Schedule/CreateScheduleRequestData.php

@@ -3,23 +3,23 @@
 namespace Cachet\Data\Requests\Schedule;
 
 use Cachet\Data\BaseData;
+use Cachet\Data\Casts\FlexibleDateTimeCast;
 use Cachet\Enums\ComponentStatusEnum;
 use Cachet\Enums\ScheduleStatusEnum;
 use Carbon\Carbon;
 use Illuminate\Validation\Rule;
 use Spatie\LaravelData\Attributes\DataCollectionOf;
 use Spatie\LaravelData\Attributes\WithCast;
-use Spatie\LaravelData\Casts\DateTimeInterfaceCast;
 use Spatie\LaravelData\Support\Validation\ValidationContext;
 
 final class CreateScheduleRequestData extends BaseData
 {
     public function __construct(
         public readonly string $name,
         public readonly string $message,
-        #[WithCast(DateTimeInterfaceCast::class, format: 'Y-m-d H:i:s')]
+        #[WithCast(FlexibleDateTimeCast::class)]
         public readonly Carbon $scheduledAt,
-        #[WithCast(DateTimeInterfaceCast::class, format: 'Y-m-d H:i:s')]
+        #[WithCast(FlexibleDateTimeCast::class)]
         public readonly ?Carbon $completedAt = null,
         public readonly ?ScheduleStatusEnum $status = null,
         public readonly bool $notifications = false,
@@ -34,12 +34,25 @@ public static function rules(ValidationContext $context): array
         return [
             'name' => ['required', 'string', 'max:255'],
             'message' => ['required', 'string'],
+            /**
+             * The date/time the maintenance window starts, e.g. "2023-11-07 05:31:56" or ISO 8601.
+             */
             'scheduled_at' => ['required', 'date'],
+            /**
+             * The date/time the maintenance window ends, e.g. "2023-11-07 05:31:56" or ISO 8601.
+             */
             'completed_at' => ['nullable', 'date'],
             'notifications' => ['boolean'],
             'components' => ['array'],
-            'components.*.id' => ['required_with:components', 'int', 'exists:components,id'],
-            'components.*.status' => ['required_with:components', 'int', Rule::enum(ComponentStatusEnum::class)],
+            'components.*.id' => ['required', 'int', 'exists:components,id'],
+            'components.*.status' => ['required', 'int', Rule::enum(ComponentStatusEnum::class)],
+            /**
+             * Key/value metadata to store against the resource.
+             *
+             * @var array<string, mixed>|null
+             *
+             * @example {"cluster": "eu-west"}
+             */
             'meta' => ['nullable', 'array'],
         ];
     }

src/Data/Requests/Schedule/UpdateScheduleRequestData.php

@@ -3,13 +3,13 @@
 namespace Cachet\Data\Requests\Schedule;
 
 use Cachet\Data\BaseData;
+use Cachet\Data\Casts\FlexibleDateTimeCast;
 use Cachet\Enums\ComponentStatusEnum;
 use Cachet\Enums\ScheduleStatusEnum;
 use Carbon\Carbon;
 use Illuminate\Validation\Rule;
 use Spatie\LaravelData\Attributes\DataCollectionOf;
 use Spatie\LaravelData\Attributes\WithCast;
-use Spatie\LaravelData\Casts\DateTimeInterfaceCast;
 use Spatie\LaravelData\Support\Validation\ValidationContext;
 
 final class UpdateScheduleRequestData extends BaseData
@@ -18,9 +18,9 @@ public function __construct(
         public readonly ?string $name = null,
         public readonly ?string $message = null,
         public readonly ?ScheduleStatusEnum $status = null,
-        #[WithCast(DateTimeInterfaceCast::class, format: 'Y-m-d H:i:s')]
+        #[WithCast(FlexibleDateTimeCast::class)]
         public readonly ?Carbon $scheduledAt = null,
-        #[WithCast(DateTimeInterfaceCast::class, format: 'Y-m-d H:i:s')]
+        #[WithCast(FlexibleDateTimeCast::class)]
         public readonly ?Carbon $completedAt = null,
         #[DataCollectionOf(ScheduleComponentRequestData::class)]
         public readonly ?array $components = null,
@@ -33,11 +33,24 @@ public static function rules(ValidationContext $context): array
         return [
             'name' => ['string', 'max:255'],
             'message' => ['string'],
+            /**
+             * The date/time the maintenance window starts, e.g. "2023-11-07 05:31:56" or ISO 8601.
+             */
             'scheduled_at' => ['nullable', 'date'],
+            /**
+             * The date/time the maintenance window ends, e.g. "2023-11-07 05:31:56" or ISO 8601.
+             */
             'completed_at' => ['nullable', 'date'],
             'components' => ['array'],
-            'components.*.id' => ['required_with:components', 'int', 'exists:components,id'],
-            'components.*.status' => ['required_with:components', Rule::enum(ComponentStatusEnum::class)],
+            'components.*.id' => ['required', 'int', 'exists:components,id'],
+            'components.*.status' => ['required', Rule::enum(ComponentStatusEnum::class)],
+            /**
+             * Key/value metadata to store against the resource.
+             *
+             * @var array<string, mixed>|null
+             *
+             * @example {"cluster": "eu-west"}
+             */
             'meta' => ['nullable', 'array'],
         ];
     }

src/Data/Requests/ScheduleUpdate/CreateScheduleUpdateRequestData.php

@@ -3,23 +3,26 @@
 namespace Cachet\Data\Requests\ScheduleUpdate;
 
 use Cachet\Data\BaseData;
+use Cachet\Data\Casts\FlexibleDateTimeCast;
 use Carbon\Carbon;
 use Spatie\LaravelData\Attributes\WithCast;
-use Spatie\LaravelData\Casts\DateTimeInterfaceCast;
 use Spatie\LaravelData\Support\Validation\ValidationContext;
 
 final class CreateScheduleUpdateRequestData extends BaseData
 {
     public function __construct(
         public readonly string $message,
-        #[WithCast(DateTimeInterfaceCast::class, format: 'Y-m-d H:i:s')]
+        #[WithCast(FlexibleDateTimeCast::class)]
         public readonly ?Carbon $completedAt = null,
     ) {}
 
     public static function rules(ValidationContext $context): array
     {
         return [
             'message' => ['required', 'string'],
+            /**
+             * The date/time the maintenance window ended, e.g. "2023-11-07 05:31:56" or ISO 8601.
+             */
             'completed_at' => ['nullable', 'date'],
         ];
     }

src/Data/Requests/Subscriber/CreateSubscriberRequestData.php

@@ -25,6 +25,13 @@ public static function rules(ValidationContext $context): array
             'components' => ['array'],
             'components.*' => ['int', 'min:0', Rule::exists('components', 'id')],
             'verified' => ['bool'],
+            /**
+             * Key/value metadata to store against the resource.
+             *
+             * @var array<string, mixed>|null
+             *
+             * @example {"cluster": "eu-west"}
+             */
             'meta' => ['nullable', 'array'],
         ];
     }