[v2] feat: add version api endpoint

app/Filament/Resources/ApiTokens/Schemas/ApiTokenForm.php

@@ -25,13 +25,15 @@ public static function schema(): array
                             'results:read' => __('api_tokens.read_results'),
                             'speedtests:run' => __('general.run_speedtest'),
                             'ookla:list-servers' => __('general.list_servers'),
+                            'admin:read' => __('api_tokens.admin_read'),
                         ])
                         ->required()
                         ->bulkToggleable()
                         ->descriptions([
                             'results:read' => __('api_tokens.read_results_description'),
                             'speedtests:run' => __('api_tokens.run_speedtest_description'),
                             'ookla:list-servers' => __('api_tokens.list_servers_description'),
+                            'admin:read' => __('api_tokens.admin_read_description'),
                         ]),
                     DateTimePicker::make('expires_at')
                         ->label(__('api_tokens.expires_at'))

app/Http/Controllers/Api/V1/VersionController.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Services\GitHub\Repository;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+
+class VersionController extends ApiController
+{
+    /**
+     * GET /api/v1/version
+     * Returns the currently installed application version and update information.
+     * Restricted to admin users only.
+     */
+    public function __invoke(Request $request)
+    {
+        if ($request->user()->tokenCant('admin:read')) {
+            return $this->sendResponse(
+                data: null,
+                message: 'You do not have permission to view version information.',
+                code: Response::HTTP_FORBIDDEN
+            );
+        }
+
+        $latestVersion = Repository::getLatestVersion();
+
+        return $this->sendResponse(
+            data: [
+                'app' => [
+                    'version' => config('speedtest.build_version'),
+                    'build_date' => config('speedtest.build_date')->toIso8601String(),
+                ],
+                'updates' => [
+                    'latest_version' => $latestVersion ?: null,
+                    'update_available' => Repository::updateAvailable(),
+                ],
+            ]
+        );
+    }
+}

app/OpenApi/Annotations/V1/VersionAnnotations.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\OpenApi\Annotations\V1;
+
+use Illuminate\Http\Response;
+use OpenApi\Attributes as OA;
+
+#[OA\PathItem(
+    path: '/api/v1/version',
+    description: 'Endpoint for retrieving application version information.'
+)]
+class VersionAnnotations
+{
+    #[OA\Get(
+        path: '/api/v1/version',
+        summary: 'Get application version and update information',
+        description: 'Returns the currently installed application version and checks for available updates. Requires admin:read token ability.',
+        operationId: 'getVersion',
+        tags: ['Version'],
+        security: [['bearerAuth' => []]],
+        parameters: [
+            new OA\Parameter(ref: '#/components/parameters/AcceptHeader'),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: 'Version information retrieved successfully',
+                content: new OA\JsonContent(ref: '#/components/schemas/Version')
+            ),
+            new OA\Response(
+                response: Response::HTTP_UNAUTHORIZED,
+                description: 'Unauthenticated',
+                content: new OA\JsonContent(ref: '#/components/schemas/UnauthenticatedError')
+            ),
+            new OA\Response(
+                response: Response::HTTP_FORBIDDEN,
+                description: 'Forbidden - Missing admin:read token ability',
+                content: new OA\JsonContent(ref: '#/components/schemas/ForbiddenError')
+            ),
+            new OA\Response(
+                response: Response::HTTP_NOT_ACCEPTABLE,
+                description: 'Not Acceptable - Missing or invalid Accept header',
+                content: new OA\JsonContent(ref: '#/components/schemas/NotAcceptableError')
+            ),
+        ]
+    )]
+    public function getVersion(): void {}
+}

app/OpenApi/OpenApiDefinition.php

@@ -42,6 +42,10 @@
             name: 'Stats',
             description: 'Endpoints for retrieving aggregated statistics and performance metrics. Requires `speedtests:read` token scope.'
         ),
+        new OA\Tag(
+            name: 'Version',
+            description: 'Endpoint for retrieving application version and update information. Requires `admin:read` token scope.'
+        ),
     ]
 )]
 class OpenApiDefinition {}

app/OpenApi/Schemas/VersionSchema.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace App\OpenApi\Schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'Version',
+    title: 'Version',
+    description: 'Application version and update information',
+    type: 'object',
+    properties: [
+        new OA\Property(
+            property: 'data',
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: 'app',
+                    type: 'object',
+                    properties: [
+                        new OA\Property(
+                            property: 'version',
+                            type: 'string',
+                            example: 'v1.13.7'
+                        ),
+                        new OA\Property(
+                            property: 'build_date',
+                            type: 'string',
+                            format: 'date-time',
+                            example: '2026-02-04T00:00:00+00:00'
+                        ),
+                    ]
+                ),
+                new OA\Property(
+                    property: 'updates',
+                    type: 'object',
+                    properties: [
+                        new OA\Property(
+                            property: 'latest_version',
+                            type: 'string',
+                            nullable: true,
+                            example: 'v1.13.8'
+                        ),
+                        new OA\Property(
+                            property: 'update_available',
+                            type: 'boolean',
+                            example: true
+                        ),
+                    ]
+                ),
+            ]
+        ),
+        new OA\Property(
+            property: 'message',
+            type: 'string',
+            example: 'ok'
+        ),
+    ]
+)]
+class VersionSchema {}

lang/en/api_tokens.php

@@ -27,4 +27,6 @@
     'read_results_description' => 'The token will have permission to read results and statistics.',
     'run_speedtest_description' => 'The token will have permission to run speedtest.',
     'list_servers_description' => 'The token will have permission to list servers.',
+    'admin_read' => 'Admin read',
+    'admin_read_description' => 'The token will have permission to read administrative information such as application version.',
 ];

openapi.json

@@ -269,6 +269,69 @@
                 }
             }
         },
+        "/api/v1/version": {
+            "description": "Endpoint for retrieving application version information.",
+            "get": {
+                "tags": [
+                    "Version"
+                ],
+                "summary": "Get application version and update information",
+                "description": "Returns the currently installed application version and checks for available updates. Requires admin:read token ability.",
+                "operationId": "getVersion",
+                "parameters": [
+                    {
+                        "$ref": "#/components/parameters/AcceptHeader"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Version information retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/Version"
+                                }
+                            }
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthenticated",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/UnauthenticatedError"
+                                }
+                            }
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden - Missing admin:read token ability",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ForbiddenError"
+                                }
+                            }
+                        }
+                    },
+                    "406": {
+                        "description": "Not Acceptable - Missing or invalid Accept header",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/NotAcceptableError"
+                                }
+                            }
+                        }
+                    }
+                },
+                "security": [
+                    {
+                        "bearerAuth": []
+                    }
+                ]
+            }
+        },
         "/api/v1/ookla/list-servers": {
             "get": {
                 "tags": [
@@ -1146,6 +1209,50 @@
                     }
                 },
                 "type": "object"
+            },
+            "Version": {
+                "title": "Version",
+                "description": "Application version and update information",
+                "properties": {
+                    "data": {
+                        "properties": {
+                            "app": {
+                                "properties": {
+                                    "version": {
+                                        "type": "string",
+                                        "example": "v1.13.7"
+                                    },
+                                    "build_date": {
+                                        "type": "string",
+                                        "format": "date-time",
+                                        "example": "2026-02-04T00:00:00+00:00"
+                                    }
+                                },
+                                "type": "object"
+                            },
+                            "updates": {
+                                "properties": {
+                                    "latest_version": {
+                                        "type": "string",
+                                        "example": "v1.13.8",
+                                        "nullable": true
+                                    },
+                                    "update_available": {
+                                        "type": "boolean",
+                                        "example": true
+                                    }
+                                },
+                                "type": "object"
+                            }
+                        },
+                        "type": "object"
+                    },
+                    "message": {
+                        "type": "string",
+                        "example": "ok"
+                    }
+                },
+                "type": "object"
             }
         },
         "parameters": {
@@ -1181,6 +1288,10 @@
             "name": "Stats",
             "description": "Endpoints for retrieving aggregated statistics and performance metrics. Requires `speedtests:read` token scope."
         },
+        {
+            "name": "Version",
+            "description": "Endpoint for retrieving application version and update information. Requires `admin:read` token scope."
+        },
         {
             "name": "Servers",
             "description": "Servers"

routes/api/v1/routes.php

@@ -4,6 +4,7 @@
 use App\Http\Controllers\Api\V1\ResultsController;
 use App\Http\Controllers\Api\V1\SpeedtestController;
 use App\Http\Controllers\Api\V1\StatsController;
+use App\Http\Controllers\Api\V1\VersionController;
 use Illuminate\Support\Facades\Route;
 
 Route::prefix('v1')->name('api.v1.')->group(function () {
@@ -24,4 +25,7 @@
 
     Route::get('/stats', StatsController::class)
         ->name('stats.aggregated');
+
+    Route::get('/version', VersionController::class)
+        ->name('version');
 });