feat(environments-client): scalar value types Text, Number, Boolean, Options (ER-5350)

.changeset/environments-client-scalar-types.md

@@ -0,0 +1,17 @@
+---
+"@epilot/environments-client": minor
+"@epilot/sdk": minor
+"@epilot/cli": patch
+---
+
+Add the scalar environment variable types `Text`, `Number`, `Boolean` and `Options` (ER-5350)
+
+`EnvironmentValueType` widens from `"String" | "SecretString"` to include `Text`, `Number`, `Boolean` and `Options`, and a variable's `value` widens from `string` to `string | number | boolean | OptionsValue` accordingly — a `Number` variable holds a JSON number, a `Boolean` a JSON boolean, and an `Options` variable an object of selectable entries. Two new exported types come with it: `EnvironmentValue` for the value union and `EnvironmentOption` for one entry of an `Options` list, which carries either a single `label` or a `labels` map keyed by language.
+
+The split matters to browser-facing consumers: `Text`, `Number`, `Boolean` and `Options` may be served to a browser, while `String` and `SecretString` may not. `SecretString` keeps its existing behaviour — encrypted at rest, value never returned.
+
+`value` also becomes genuinely optional rather than merely absent for secrets: a variable created without one — as a blueprint install does, syncing a variable's key and type but never its value — reads back with no `value` at all.
+
+`protected` is now declared on the variable payloads, marking a variable as guarded against editing.
+
+Consumers that exhaustively switch on `EnvironmentValueType`, or that assign `value` straight to a `string`, will need to widen. Everything that only reads `String` and `SecretString` variables is unaffected at runtime.

clients/environments-client/src/openapi.d.ts

@@ -20,55 +20,158 @@ declare namespace Components {
         export interface EnvironmentGroupUpsertRequest {
             description?: string;
         }
-        export type EnvironmentValueType = "String" | "SecretString";
+        export type EnvironmentOption = {
+            value: string;
+            label: string;
+        } | {
+            value: string;
+            labels: {
+                [name: string]: string;
+            };
+        };
+        /**
+         * A variable's value. The JSON type corresponds to the variable's `type`:
+         * `String`, `SecretString` and `Text` are strings, `Number` is a number,
+         * `Boolean` is a boolean, and `Options` is an object. Numbers are IEEE 754
+         * doubles; integers above 2^53 may lose precision on round-trip.
+         *
+         */
+        export type EnvironmentValue = /**
+         * A variable's value. The JSON type corresponds to the variable's `type`:
+         * `String`, `SecretString` and `Text` are strings, `Number` is a number,
+         * `Boolean` is a boolean, and `Options` is an object. Numbers are IEEE 754
+         * doubles; integers above 2^53 may lose precision on round-trip.
+         *
+         */
+        string | number | boolean | OptionsValue;
+        /**
+         * The structure a variable's value holds. `SecretString` is encrypted at rest and
+         * its value is never returned. `Text`, `Number`, `Boolean` and `Options` may be
+         * served to browser-facing consumers; `String` and `SecretString` may not.
+         *
+         */
+        export type EnvironmentValueType = "String" | "SecretString" | "Text" | "Number" | "Boolean" | "Options";
         export interface EnvironmentVariable {
             key: string; // ^[a-z0-9][a-z0-9_.\-]{0,127}$
-            type: EnvironmentValueType;
+            type: /**
+             * The structure a variable's value holds. `SecretString` is encrypted at rest and
+             * its value is never returned. `Text`, `Number`, `Boolean` and `Options` may be
+             * served to browser-facing consumers; `String` and `SecretString` may not.
+             *
+             */
+            EnvironmentValueType;
             description?: string;
             /**
              * Optional group name for organising variables in the UI
              */
             group?: string;
             /**
-             * Value is returned for String type, omitted for SecretString
+             * Returned for non-secret types, omitted for SecretString. Also omitted when
+             * the variable has been created without a value — for example by a blueprint
+             * install, which syncs a variable's key and type but never its value.
+             *
+             */
+            value?: /**
+             * Returned for non-secret types, omitted for SecretString. Also omitted when
+             * the variable has been created without a value — for example by a blueprint
+             * install, which syncs a variable's key and type but never its value.
+             *
              */
-            value?: string;
+            string | number | boolean | OptionsValue;
+            /**
+             * Whether the variable is protected from editing
+             */
+            protected?: boolean;
             created_at: string; // date-time
             updated_at: string; // date-time
         }
         export interface EnvironmentVariableCreateRequest {
             key: string; // ^[a-z0-9][a-z0-9_.\-]{0,127}$
-            type: EnvironmentValueType;
+            type: /**
+             * The structure a variable's value holds. `SecretString` is encrypted at rest and
+             * its value is never returned. `Text`, `Number`, `Boolean` and `Options` may be
+             * served to browser-facing consumers; `String` and `SecretString` may not.
+             *
+             */
+            EnvironmentValueType;
             description?: string;
             group?: string;
-            value?: string;
+            value?: /**
+             * A variable's value. The JSON type corresponds to the variable's `type`:
+             * `String`, `SecretString` and `Text` are strings, `Number` is a number,
+             * `Boolean` is a boolean, and `Options` is an object. Numbers are IEEE 754
+             * doubles; integers above 2^53 may lose precision on round-trip.
+             *
+             */
+            EnvironmentValue;
+            /**
+             * Whether the variable is protected from editing
+             */
+            protected?: boolean;
         }
         export interface EnvironmentVariableList {
             items: EnvironmentVariableListItem[];
         }
         export interface EnvironmentVariableListItem {
             key: string;
-            type: EnvironmentValueType;
+            type: /**
+             * The structure a variable's value holds. `SecretString` is encrypted at rest and
+             * its value is never returned. `Text`, `Number`, `Boolean` and `Options` may be
+             * served to browser-facing consumers; `String` and `SecretString` may not.
+             *
+             */
+            EnvironmentValueType;
             description?: string;
             /**
              * Optional group name for organising variables in the UI
              */
             group?: string;
             /**
-             * Value is returned for String type, omitted for SecretString
+             * Returned for non-secret types, omitted for SecretString. Also omitted when
+             * the variable has been created without a value — for example by a blueprint
+             * install, which syncs a variable's key and type but never its value.
+             *
+             */
+            value?: /**
+             * Returned for non-secret types, omitted for SecretString. Also omitted when
+             * the variable has been created without a value — for example by a blueprint
+             * install, which syncs a variable's key and type but never its value.
+             *
+             */
+            string | number | boolean | OptionsValue;
+            /**
+             * Whether the variable is protected from editing
              */
-            value?: string;
+            protected?: boolean;
             created_at: string; // date-time
             updated_at: string; // date-time
         }
         export interface EnvironmentVariableUpdateRequest {
             /**
              * Type of variable. Used when creating a new variable. Defaults to String.
              */
-            type?: "String" | "SecretString";
-            value?: string;
+            type?: "String" | "SecretString" | "Text" | "Number" | "Boolean" | "Options";
+            value?: /**
+             * A variable's value. The JSON type corresponds to the variable's `type`:
+             * `String`, `SecretString` and `Text` are strings, `Number` is a number,
+             * `Boolean` is a boolean, and `Options` is an object. Numbers are IEEE 754
+             * doubles; integers above 2^53 may lose precision on round-trip.
+             *
+             */
+            EnvironmentValue;
             description?: string;
             group?: string;
+            /**
+             * Whether the variable is protected from editing
+             */
+            protected?: boolean;
+        }
+        export interface OptionsValue {
+            fallbackLanguage?: string;
+            options: [
+                EnvironmentOption,
+                ...EnvironmentOption[]
+            ];
         }
     }
 }
@@ -176,6 +279,8 @@ declare namespace Paths {
             }
             export interface $403 {
             }
+            export interface $409 {
+            }
             export interface $500 {
             }
         }
@@ -201,7 +306,7 @@ declare namespace Paths {
 
 export interface OperationMethods {
   /**
-   * listEnvironmentVariables - List environment variables
+   * listEnvironmentVariables - listEnvironmentVariables
    * 
    * List all environment variables for the organization. Returns metadata only, no secret values.
    */
@@ -211,17 +316,17 @@ export interface OperationMethods {
     config?: AxiosRequestConfig  
   ): OperationResponse<Paths.ListEnvironmentVariables.Responses.$200>
   /**
-   * createEnvironmentVariable - Create environment variable
+   * createEnvironmentVariable - createEnvironmentVariable
    * 
-   * Create a new environment variable or secret for the organization.
+   * Create a new environment variable or secret for the organization. If `group` is provided and the group does not yet exist, it is created automatically.
    */
   'createEnvironmentVariable'(
     parameters?: Parameters<UnknownParamsObject> | null,
     data?: Paths.CreateEnvironmentVariable.RequestBody,
     config?: AxiosRequestConfig  
   ): OperationResponse<Paths.CreateEnvironmentVariable.Responses.$201>
   /**
-   * listEnvironmentGroups - List environment groups
+   * listEnvironmentGroups - listEnvironmentGroups
    * 
    * List all environment groups for the organization.
    */
@@ -232,14 +337,16 @@ export interface OperationMethods {
   ): OperationResponse<Paths.ListEnvironmentGroups.Responses.$200>
   /**
    * putEnvironmentGroup - putEnvironmentGroup
+   * 
+   * Create or update an environment group by name. Acts as an upsert — creates the group if it does not exist.
    */
   'putEnvironmentGroup'(
     parameters?: Parameters<Paths.V1EnvironmentsGroups$Name.PathParameters> | null,
     data?: Paths.PutEnvironmentGroup.RequestBody,
     config?: AxiosRequestConfig  
   ): OperationResponse<Paths.PutEnvironmentGroup.Responses.$200 | Paths.PutEnvironmentGroup.Responses.$201>
   /**
-   * deleteEnvironmentGroup - Delete an environment group
+   * deleteEnvironmentGroup - deleteEnvironmentGroup
    * 
    * Deletes a group. Variables assigned to this group become ungrouped.
    */
@@ -249,27 +356,27 @@ export interface OperationMethods {
     config?: AxiosRequestConfig  
   ): OperationResponse<Paths.DeleteEnvironmentGroup.Responses.$204>
   /**
-   * getEnvironmentVariable - Get environment variable
+   * getEnvironmentVariable - getEnvironmentVariable
    * 
-   * Get an environment variable by key. Returns value only for String type, omitted for SecretString.
+   * Get an environment variable by key. Returns value for non-secret types, omitted for SecretString.
    */
   'getEnvironmentVariable'(
     parameters?: Parameters<Paths.V1Environments$Key.PathParameters> | null,
     data?: any,
     config?: AxiosRequestConfig  
   ): OperationResponse<Paths.GetEnvironmentVariable.Responses.$200>
   /**
-   * updateEnvironmentVariable - Update environment variable
+   * updateEnvironmentVariable - updateEnvironmentVariable
    * 
-   * Create or update an environment variable. Acts as an upsert — creates the variable if it does not exist.
+   * Create or update an environment variable. Acts as an upsert — creates the variable if it does not exist. If `group` is provided and the group does not yet exist, it is created automatically.
    */
   'updateEnvironmentVariable'(
     parameters?: Parameters<Paths.V1Environments$Key.PathParameters> | null,
     data?: Paths.UpdateEnvironmentVariable.RequestBody,
     config?: AxiosRequestConfig  
   ): OperationResponse<Paths.UpdateEnvironmentVariable.Responses.$200 | Paths.UpdateEnvironmentVariable.Responses.$201>
   /**
-   * deleteEnvironmentVariable - Delete environment variable
+   * deleteEnvironmentVariable - deleteEnvironmentVariable
    * 
    * Delete an environment variable by key.
    */
@@ -283,7 +390,7 @@ export interface OperationMethods {
 export interface PathsDictionary {
   ['/v1/environments']: {
     /**
-     * listEnvironmentVariables - List environment variables
+     * listEnvironmentVariables - listEnvironmentVariables
      * 
      * List all environment variables for the organization. Returns metadata only, no secret values.
      */
@@ -293,9 +400,9 @@ export interface PathsDictionary {
       config?: AxiosRequestConfig  
     ): OperationResponse<Paths.ListEnvironmentVariables.Responses.$200>
     /**
-     * createEnvironmentVariable - Create environment variable
+     * createEnvironmentVariable - createEnvironmentVariable
      * 
-     * Create a new environment variable or secret for the organization.
+     * Create a new environment variable or secret for the organization. If `group` is provided and the group does not yet exist, it is created automatically.
      */
     'post'(
       parameters?: Parameters<UnknownParamsObject> | null,
@@ -305,7 +412,7 @@ export interface PathsDictionary {
   }
   ['/v1/environments/groups']: {
     /**
-     * listEnvironmentGroups - List environment groups
+     * listEnvironmentGroups - listEnvironmentGroups
      * 
      * List all environment groups for the organization.
      */
@@ -318,14 +425,16 @@ export interface PathsDictionary {
   ['/v1/environments/groups/{name}']: {
     /**
      * putEnvironmentGroup - putEnvironmentGroup
+     * 
+     * Create or update an environment group by name. Acts as an upsert — creates the group if it does not exist.
      */
     'put'(
       parameters?: Parameters<Paths.V1EnvironmentsGroups$Name.PathParameters> | null,
       data?: Paths.PutEnvironmentGroup.RequestBody,
       config?: AxiosRequestConfig  
     ): OperationResponse<Paths.PutEnvironmentGroup.Responses.$200 | Paths.PutEnvironmentGroup.Responses.$201>
     /**
-     * deleteEnvironmentGroup - Delete an environment group
+     * deleteEnvironmentGroup - deleteEnvironmentGroup
      * 
      * Deletes a group. Variables assigned to this group become ungrouped.
      */
@@ -337,27 +446,27 @@ export interface PathsDictionary {
   }
   ['/v1/environments/{key}']: {
     /**
-     * getEnvironmentVariable - Get environment variable
+     * getEnvironmentVariable - getEnvironmentVariable
      * 
-     * Get an environment variable by key. Returns value only for String type, omitted for SecretString.
+     * Get an environment variable by key. Returns value for non-secret types, omitted for SecretString.
      */
     'get'(
       parameters?: Parameters<Paths.V1Environments$Key.PathParameters> | null,
       data?: any,
       config?: AxiosRequestConfig  
     ): OperationResponse<Paths.GetEnvironmentVariable.Responses.$200>
     /**
-     * updateEnvironmentVariable - Update environment variable
+     * updateEnvironmentVariable - updateEnvironmentVariable
      * 
-     * Create or update an environment variable. Acts as an upsert — creates the variable if it does not exist.
+     * Create or update an environment variable. Acts as an upsert — creates the variable if it does not exist. If `group` is provided and the group does not yet exist, it is created automatically.
      */
     'put'(
       parameters?: Parameters<Paths.V1Environments$Key.PathParameters> | null,
       data?: Paths.UpdateEnvironmentVariable.RequestBody,
       config?: AxiosRequestConfig  
     ): OperationResponse<Paths.UpdateEnvironmentVariable.Responses.$200 | Paths.UpdateEnvironmentVariable.Responses.$201>
     /**
-     * deleteEnvironmentVariable - Delete environment variable
+     * deleteEnvironmentVariable - deleteEnvironmentVariable
      * 
      * Delete an environment variable by key.
      */
@@ -375,9 +484,12 @@ export type Client = OpenAPIClient<OperationMethods, PathsDictionary>
 export type EnvironmentGroup = Components.Schemas.EnvironmentGroup;
 export type EnvironmentGroupList = Components.Schemas.EnvironmentGroupList;
 export type EnvironmentGroupUpsertRequest = Components.Schemas.EnvironmentGroupUpsertRequest;
+export type EnvironmentOption = Components.Schemas.EnvironmentOption;
+export type EnvironmentValue = Components.Schemas.EnvironmentValue;
 export type EnvironmentValueType = Components.Schemas.EnvironmentValueType;
 export type EnvironmentVariable = Components.Schemas.EnvironmentVariable;
 export type EnvironmentVariableCreateRequest = Components.Schemas.EnvironmentVariableCreateRequest;
 export type EnvironmentVariableList = Components.Schemas.EnvironmentVariableList;
 export type EnvironmentVariableListItem = Components.Schemas.EnvironmentVariableListItem;
 export type EnvironmentVariableUpdateRequest = Components.Schemas.EnvironmentVariableUpdateRequest;
+export type OptionsValue = Components.Schemas.OptionsValue;