Merge pull request 'codex/v0.5-webhook-notification/02-project-notification-settings-ui' (#48) from codex/v0.5-webhook-notification/02-project-notification-settings-ui into main

Reviewed-on: OpenSource/KanbanGit#48

app/Actions/Notifications/BuildProjectNotificationSettingsPayload.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace App\Actions\Notifications;
+
+use App\Enums\NotificationChannel;
+use App\Enums\NotificationEventType;
+use App\Http\Resources\NotificationActionResource;
+use App\Http\Resources\ProjectResource;
+use App\Models\Project;
+
+class BuildProjectNotificationSettingsPayload
+{
+    public function __construct(
+        private readonly ListProjectNotificationActions $listProjectNotificationActions,
+    ) {}
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function handle(Project $project, mixed $status = null): array
+    {
+        return [
+            'channelOptions' => NotificationChannel::options(),
+            'eventTypeOptions' => NotificationEventType::options(),
+            'notificationActions' => NotificationActionResource::collection(
+                $this->listProjectNotificationActions->handle($project),
+            )->resolve(),
+            'project' => ProjectResource::make($project)->resolve(),
+            'status' => $status,
+            'templateVariables' => $this->templateVariables(),
+        ];
+    }
+
+    /**
+     * @return array<int, array{description: string, value: string}>
+     */
+    private function templateVariables(): array
+    {
+        return [
+            [
+                'description' => 'Absolute ticket URL for the status change event.',
+                'value' => '$url',
+            ],
+            [
+                'description' => 'Project ticket key such as CORE-42.',
+                'value' => '$ticket_key',
+            ],
+            [
+                'description' => 'Ticket title from the changed ticket.',
+                'value' => '$ticket_title',
+            ],
+            [
+                'description' => 'Project name that owns the ticket.',
+                'value' => '$project_name',
+            ],
+            [
+                'description' => 'Origin status label before the move.',
+                'value' => '$status_from',
+            ],
+            [
+                'description' => 'Destination status label after the move.',
+                'value' => '$status_to',
+            ],
+            [
+                'description' => 'Actor name when the move has a known user.',
+                'value' => '$actor_name',
+            ],
+        ];
+    }
+}

app/Actions/Notifications/DeleteProjectNotificationAction.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Actions\Notifications;
+
+use App\Models\NotificationAction;
+use App\Models\Project;
+
+class DeleteProjectNotificationAction
+{
+    public function handle(Project $project, NotificationAction $notificationAction): void
+    {
+        $project->notificationActions()
+            ->whereKey($notificationAction->id)
+            ->firstOrFail()
+            ->delete();
+    }
+}

app/Actions/Notifications/ListProjectNotificationActions.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Actions\Notifications;
+
+use App\Models\NotificationAction;
+use App\Models\Project;
+use Illuminate\Database\Eloquent\Collection;
+
+class ListProjectNotificationActions
+{
+    /**
+     * @return Collection<int, NotificationAction>
+     */
+    public function handle(Project $project): Collection
+    {
+        return $project->notificationActions()->get();
+    }
+}

app/Actions/Notifications/StoreProjectNotificationAction.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Actions\Notifications;
+
+use App\Models\NotificationAction;
+use App\Models\Project;
+use Illuminate\Support\Arr;
+
+class StoreProjectNotificationAction
+{
+    /**
+     * @param  array{
+     *     channel: mixed,
+     *     channel_configuration?: array<string, mixed>|null,
+     *     delivery_url: string,
+     *     enabled: bool,
+     *     event_type: mixed,
+     *     message_template?: string|null,
+     *     name: string
+     * }  $validated
+     */
+    public function handle(Project $project, array $validated): NotificationAction
+    {
+        return $project->notificationActions()->create([
+            'channel' => Arr::get($validated, 'channel'),
+            'channel_configuration' => Arr::get($validated, 'channel_configuration') ?? [],
+            'delivery_url' => trim((string) Arr::get($validated, 'delivery_url')),
+            'enabled' => (bool) Arr::get($validated, 'enabled'),
+            'event_type' => Arr::get($validated, 'event_type'),
+            'message_template' => $this->normalizeMessageTemplate(Arr::get($validated, 'message_template')),
+            'name' => trim((string) Arr::get($validated, 'name')),
+        ]);
+    }
+
+    private function normalizeMessageTemplate(mixed $messageTemplate): ?string
+    {
+        if (! is_string($messageTemplate)) {
+            return null;
+        }
+
+        $messageTemplate = trim($messageTemplate);
+
+        return $messageTemplate === '' ? null : $messageTemplate;
+    }
+}

app/Actions/Notifications/UpdateProjectNotificationAction.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace App\Actions\Notifications;
+
+use App\Models\NotificationAction;
+use App\Models\Project;
+use Illuminate\Support\Arr;
+
+class UpdateProjectNotificationAction
+{
+    /**
+     * @param  array{
+     *     channel?: mixed,
+     *     channel_configuration?: array<string, mixed>|null,
+     *     delivery_url?: string|null,
+     *     enabled?: bool,
+     *     event_type?: mixed,
+     *     message_template?: string|null,
+     *     name?: string
+     * }  $validated
+     */
+    public function handle(
+        Project $project,
+        NotificationAction $notificationAction,
+        array $validated,
+    ): NotificationAction {
+        $notificationAction = $this->resolveProjectNotificationAction($project, $notificationAction);
+
+        $attributes = [];
+
+        if (array_key_exists('name', $validated)) {
+            $attributes['name'] = trim((string) Arr::get($validated, 'name'));
+        }
+
+        if (array_key_exists('enabled', $validated)) {
+            $attributes['enabled'] = (bool) Arr::get($validated, 'enabled');
+        }
+
+        if (array_key_exists('event_type', $validated)) {
+            $attributes['event_type'] = Arr::get($validated, 'event_type');
+        }
+
+        if (array_key_exists('channel', $validated)) {
+            $attributes['channel'] = Arr::get($validated, 'channel');
+        }
+
+        if (array_key_exists('channel_configuration', $validated)) {
+            $attributes['channel_configuration'] = Arr::get($validated, 'channel_configuration') ?? [];
+        }
+
+        if (array_key_exists('message_template', $validated)) {
+            $attributes['message_template'] = $this->normalizeMessageTemplate(
+                Arr::get($validated, 'message_template'),
+            );
+        }
+
+        $deliveryUrl = Arr::get($validated, 'delivery_url');
+
+        if (is_string($deliveryUrl) && trim($deliveryUrl) !== '') {
+            $attributes['delivery_url'] = trim($deliveryUrl);
+        }
+
+        $notificationAction->update($attributes);
+
+        return $notificationAction->fresh();
+    }
+
+    private function normalizeMessageTemplate(mixed $messageTemplate): ?string
+    {
+        if (! is_string($messageTemplate)) {
+            return null;
+        }
+
+        $messageTemplate = trim($messageTemplate);
+
+        return $messageTemplate === '' ? null : $messageTemplate;
+    }
+
+    private function resolveProjectNotificationAction(
+        Project $project,
+        NotificationAction $notificationAction,
+    ): NotificationAction {
+        return $project->notificationActions()
+            ->whereKey($notificationAction->id)
+            ->firstOrFail();
+    }
+}

app/Enums/NotificationChannel.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace App\Enums;
+
+enum NotificationChannel: string
+{
+    case Discord = 'discord';
+    case Webhook = 'webhook';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Discord => 'Discord',
+            self::Webhook => 'Webhook',
+        };
+    }
+
+    /**
+     * @return array<int, array{label: string, value: string}>
+     */
+    public static function options(): array
+    {
+        return array_map(
+            fn (self $channel): array => [
+                'label' => $channel->label(),
+                'value' => $channel->value,
+            ],
+            self::cases(),
+        );
+    }
+}

app/Enums/NotificationDeliveryStatus.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Enums;
+
+enum NotificationDeliveryStatus: string
+{
+    case Failed = 'failed';
+    case Pending = 'pending';
+    case Retryable = 'retryable';
+    case Succeeded = 'succeeded';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Failed => 'Failed',
+            self::Pending => 'Pending',
+            self::Retryable => 'Retryable',
+            self::Succeeded => 'Succeeded',
+        };
+    }
+}

app/Enums/NotificationEventType.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Enums;
+
+enum NotificationEventType: string
+{
+    case TicketStatusChanged = 'ticket_status_changed';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::TicketStatusChanged => 'Ticket status changed',
+        };
+    }
+
+    /**
+     * @return array<int, array{label: string, value: string}>
+     */
+    public static function options(): array
+    {
+        return array_map(
+            fn (self $eventType): array => [
+                'label' => $eventType->label(),
+                'value' => $eventType->value,
+            ],
+            self::cases(),
+        );
+    }
+}

app/Http/Controllers/ProjectNotificationSettingsController.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Actions\Notifications\BuildProjectNotificationSettingsPayload;
+use App\Actions\Notifications\DeleteProjectNotificationAction;
+use App\Actions\Notifications\StoreProjectNotificationAction;
+use App\Actions\Notifications\UpdateProjectNotificationAction;
+use App\Actions\Permissions\PermissionService;
+use App\Enums\Permission;
+use App\Http\Requests\StoreProjectNotificationActionRequest;
+use App\Http\Requests\UpdateProjectNotificationActionRequest;
+use App\Models\NotificationAction;
+use App\Models\Project;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Inertia\Inertia;
+use Inertia\Response;
+
+class ProjectNotificationSettingsController extends Controller
+{
+    public function __construct(
+        private readonly BuildProjectNotificationSettingsPayload $buildProjectNotificationSettingsPayload,
+        private readonly DeleteProjectNotificationAction $deleteProjectNotificationAction,
+        private readonly PermissionService $permissionService,
+        private readonly StoreProjectNotificationAction $storeProjectNotificationAction,
+        private readonly UpdateProjectNotificationAction $updateProjectNotificationAction,
+    ) {}
+
+    public function show(Request $request, Project $project): Response
+    {
+        $this->abortUnlessCanManage($request, $project);
+
+        return Inertia::render(
+            'projects/settings/Notifications',
+            $this->buildProjectNotificationSettingsPayload->handle($project, session('status')),
+        );
+    }
+
+    public function store(
+        StoreProjectNotificationActionRequest $request,
+        Project $project,
+    ): RedirectResponse {
+        $this->abortUnlessCanManage($request, $project);
+
+        $notificationAction = $this->storeProjectNotificationAction->handle($project, $request->validated());
+
+        return to_route('projects.settings.notifications', $project)
+            ->with('status', "{$notificationAction->name} notification was added.");
+    }
+
+    public function update(
+        UpdateProjectNotificationActionRequest $request,
+        Project $project,
+        NotificationAction $notificationAction,
+    ): RedirectResponse {
+        $this->abortUnlessCanManage($request, $project);
+
+        $notificationAction = $this->updateProjectNotificationAction->handle(
+            $project,
+            $notificationAction,
+            $request->validated(),
+        );
+
+        return to_route('projects.settings.notifications', $project)
+            ->with('status', "{$notificationAction->name} notification was updated.");
+    }
+
+    public function destroy(
+        Request $request,
+        Project $project,
+        NotificationAction $notificationAction,
+    ): RedirectResponse {
+        $this->abortUnlessCanManage($request, $project);
+
+        $notificationAction = $project->notificationActions()
+            ->whereKey($notificationAction->id)
+            ->firstOrFail();
+        $deletedName = $notificationAction->name;
+
+        $this->deleteProjectNotificationAction->handle($project, $notificationAction);
+
+        return to_route('projects.settings.notifications', $project)
+            ->with('status', "{$deletedName} notification was deleted.");
+    }
+
+    private function abortUnlessCanManage(Request $request, Project $project): void
+    {
+        abort_unless(
+            $this->permissionService->allows($request->user(), Permission::ProjectAdmin, $project),
+            403,
+        );
+    }
+}

app/Http/Requests/StoreProjectNotificationActionRequest.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace App\Http\Requests;
+
+use App\Enums\NotificationChannel;
+use App\Enums\NotificationEventType;
+use Illuminate\Contracts\Validation\ValidationRule;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class StoreProjectNotificationActionRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return $this->user() !== null;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'name' => ['required', 'string', 'max:255'],
+            'event_type' => ['required', 'string', Rule::in($this->eventTypes())],
+            'channel' => ['required', 'string', Rule::in($this->channels())],
+            'enabled' => ['required', 'boolean'],
+            'delivery_url' => ['required', 'string', 'max:2048', 'url'],
+            'message_template' => $this->messageTemplateRules(),
+        ];
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function channels(): array
+    {
+        return array_map(
+            static fn (NotificationChannel $channel): string => $channel->value,
+            NotificationChannel::cases(),
+        );
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function eventTypes(): array
+    {
+        return array_map(
+            static fn (NotificationEventType $eventType): string => $eventType->value,
+            NotificationEventType::cases(),
+        );
+    }
+
+    /**
+     * @return array<int, ValidationRule|string>
+     */
+    private function messageTemplateRules(): array
+    {
+        if ($this->input('channel') === NotificationChannel::Discord->value) {
+            return ['required', 'string', 'max:2000'];
+        }
+
+        return ['nullable', 'string', 'max:2000'];
+    }
+}

app/Http/Requests/UpdateProjectNotificationActionRequest.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace App\Http\Requests;
+
+use App\Enums\NotificationChannel;
+use App\Enums\NotificationEventType;
+use Illuminate\Contracts\Validation\ValidationRule;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class UpdateProjectNotificationActionRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return $this->user() !== null;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'name' => ['required', 'string', 'max:255'],
+            'event_type' => ['required', 'string', Rule::in($this->eventTypes())],
+            'channel' => ['required', 'string', Rule::in($this->channels())],
+            'enabled' => ['required', 'boolean'],
+            'delivery_url' => ['nullable', 'string', 'max:2048', 'url'],
+            'message_template' => $this->messageTemplateRules(),
+        ];
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function channels(): array
+    {
+        return array_map(
+            static fn (NotificationChannel $channel): string => $channel->value,
+            NotificationChannel::cases(),
+        );
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function eventTypes(): array
+    {
+        return array_map(
+            static fn (NotificationEventType $eventType): string => $eventType->value,
+            NotificationEventType::cases(),
+        );
+    }
+
+    /**
+     * @return array<int, ValidationRule|string>
+     */
+    private function messageTemplateRules(): array
+    {
+        if ($this->input('channel') === NotificationChannel::Discord->value) {
+            return ['required', 'string', 'max:2000'];
+        }
+
+        return ['nullable', 'string', 'max:2000'];
+    }
+}

app/Http/Resources/NotificationActionResource.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Http\Resources;
+
+use App\Models\NotificationAction;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class NotificationActionResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'project_id' => $this->project_id,
+            'name' => $this->name,
+            'enabled' => $this->enabled,
+            'event_type' => $this->event_type->value,
+            'event_type_label' => $this->event_type->label(),
+            'channel' => $this->channel->value,
+            'channel_label' => $this->channel->label(),
+            'channel_configuration' => $this->channel_configuration ?? [],
+            'has_delivery_url' => $this->resource instanceof NotificationAction && filled($this->delivery_url),
+            'message_template' => $this->message_template,
+            'created_at' => $this->created_at?->toISOString(),
+            'updated_at' => $this->updated_at?->toISOString(),
+        ];
+    }
+}

app/Http/Resources/NotificationDeliveryLogResource.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class NotificationDeliveryLogResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'notification_action_id' => $this->notification_action_id,
+            'event_type' => $this->event_type->value,
+            'event_type_label' => $this->event_type->label(),
+            'channel' => $this->channel->value,
+            'channel_label' => $this->channel->label(),
+            'delivery_status' => $this->delivery_status->value,
+            'delivery_status_label' => $this->delivery_status->label(),
+            'attempt_count' => $this->attempt_count,
+            'http_status' => $this->http_status,
+            'response_excerpt' => $this->response_excerpt,
+            'error_excerpt' => $this->error_excerpt,
+            'payload_metadata' => $this->payload_metadata,
+            'last_attempted_at' => $this->last_attempted_at?->toISOString(),
+            'delivered_at' => $this->delivered_at?->toISOString(),
+            'created_at' => $this->created_at?->toISOString(),
+            'updated_at' => $this->updated_at?->toISOString(),
+        ];
+    }
+}

app/Models/NotificationAction.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Models;
+
+use App\Enums\NotificationChannel;
+use App\Enums\NotificationEventType;
+use Database\Factories\NotificationActionFactory;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Attributes\Hidden;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+#[Fillable([
+    'channel',
+    'channel_configuration',
+    'delivery_url',
+    'enabled',
+    'event_type',
+    'message_template',
+    'name',
+    'project_id',
+])]
+#[Hidden(['delivery_url'])]
+class NotificationAction extends Model
+{
+    /** @use HasFactory<NotificationActionFactory> */
+    use HasFactory;
+
+    /**
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'channel' => NotificationChannel::class,
+            'channel_configuration' => 'array',
+            'delivery_url' => 'encrypted',
+            'enabled' => 'boolean',
+            'event_type' => NotificationEventType::class,
+        ];
+    }
+
+    public function scopeEnabled(Builder $query): Builder
+    {
+        return $query->where('enabled', true);
+    }
+
+    public function deliveryLogs(): HasMany
+    {
+        return $this->hasMany(NotificationDeliveryLog::class)
+            ->orderByDesc('created_at')
+            ->orderByDesc('id');
+    }
+
+    public function project(): BelongsTo
+    {
+        return $this->belongsTo(Project::class);
+    }
+}

app/Models/NotificationDeliveryLog.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace App\Models;
+
+use App\Enums\NotificationChannel;
+use App\Enums\NotificationDeliveryStatus;
+use App\Enums\NotificationEventType;
+use Database\Factories\NotificationDeliveryLogFactory;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+#[Fillable([
+    'attempt_count',
+    'channel',
+    'delivered_at',
+    'delivery_status',
+    'error_excerpt',
+    'event_type',
+    'http_status',
+    'last_attempted_at',
+    'notification_action_id',
+    'payload_metadata',
+    'response_excerpt',
+])]
+class NotificationDeliveryLog extends Model
+{
+    /** @use HasFactory<NotificationDeliveryLogFactory> */
+    use HasFactory;
+
+    /**
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'attempt_count' => 'integer',
+            'channel' => NotificationChannel::class,
+            'delivered_at' => 'datetime',
+            'delivery_status' => NotificationDeliveryStatus::class,
+            'event_type' => NotificationEventType::class,
+            'http_status' => 'integer',
+            'last_attempted_at' => 'datetime',
+            'payload_metadata' => 'array',
+        ];
+    }
+
+    public function notificationAction(): BelongsTo
+    {
+        return $this->belongsTo(NotificationAction::class);
+    }
+}

app/Models/Project.php

@@ -88,6 +88,13 @@ class Project extends Model
             ->orderBy('repository_full_name');
     }
 
+    public function notificationActions(): HasMany
+    {
+        return $this->hasMany(NotificationAction::class)
+            ->orderBy('name')
+            ->orderBy('id');
+    }
+
     public function tickets(): HasMany
     {
         return $this->hasMany(Ticket::class)