feat: add typed Enum DTO to Action::param()

src/Platform/Action.php

@@ -170,9 +170,10 @@ public function getParams(): array
      * @param  bool  $deprecated
      * @param  string  $example
      * @param  array  $aliases
+     * @param  Enum|null  $enum
      * @return self
      */
-    public function param(string $key, mixed $default, Validator|callable $validator, string $description = '', bool $optional = false, array $injections = [], bool $skipValidation = false, bool $deprecated = false, string $example = '', array $aliases = []): self
+    public function param(string $key, mixed $default, Validator|callable $validator, string $description = '', bool $optional = false, array $injections = [], bool $skipValidation = false, bool $deprecated = false, string $example = '', array $aliases = [], ?Enum $enum = null): self
     {
         $param = [
             'default' => $default,
@@ -184,6 +185,7 @@ public function param(string $key, mixed $default, Validator|callable $validator
             'deprecated' => $deprecated, // TODO: @Meldiron implement tests
             'example' => $example,
             'aliases' => $aliases,
+            'enum' => $enum,
         ];
         $this->options['param:'.$key] = array_merge($param, ['type' => 'param']);
         $this->params[$key] = $param;

src/Platform/Enum.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Utopia\Platform;
+
+/**
+ * Enum metadata for whitelist-backed parameters.
+ */
+final readonly class Enum
+{
+    /**
+     * @param  string|null  $name Generated enum name.
+     * @param  array<string, string>|null  $map Mapping of whitelist values to generated enum case names.
+     * @param  list<string>|null  $exclude Whitelist values to omit from generated enums.
+     */
+    public function __construct(
+        public ?string $name = null,
+        public ?array $map = null,
+        public ?array $exclude = null,
+    ) {
+    }
+}