feat: release target eligible versions v1 endpoint (#1143)

Author: adityachoudhari26

apps/api/openapi/openapi.json

@@ -7492,6 +7492,130 @@
             "summary": "Get the desired release for a release target"
          }
       },
+      "/v1/workspaces/{workspaceId}/release-targets/{releaseTargetKey}/eligible-versions": {
+         "post": {
+            "description": "Returns deployment versions that currently pass every policy rule for this release target. An optional CEL filter narrows the result; pagination is applied to the filtered set. Use the \"version\" variable in the CEL expression to access version properties.",
+            "operationId": "listEligibleVersionsForReleaseTarget",
+            "parameters": [
+               {
+                  "description": "ID of the workspace",
+                  "in": "path",
+                  "name": "workspaceId",
+                  "required": true,
+                  "schema": {
+                     "type": "string"
+                  }
+               },
+               {
+                  "description": "Key of the release target",
+                  "in": "path",
+                  "name": "releaseTargetKey",
+                  "required": true,
+                  "schema": {
+                     "type": "string"
+                  }
+               },
+               {
+                  "description": "Maximum number of items to return",
+                  "in": "query",
+                  "name": "limit",
+                  "required": false,
+                  "schema": {
+                     "default": 50,
+                     "maximum": 1000,
+                     "minimum": 1,
+                     "type": "integer"
+                  }
+               },
+               {
+                  "description": "Number of items to skip",
+                  "in": "query",
+                  "name": "offset",
+                  "required": false,
+                  "schema": {
+                     "default": 0,
+                     "minimum": 0,
+                     "type": "integer"
+                  }
+               }
+            ],
+            "requestBody": {
+               "content": {
+                  "application/json": {
+                     "schema": {
+                        "properties": {
+                           "filter": {
+                              "description": "CEL expression to filter eligible versions. Defaults to \"true\" (all eligible versions).",
+                              "type": "string"
+                           }
+                        },
+                        "type": "object"
+                     }
+                  }
+               },
+               "required": true
+            },
+            "responses": {
+               "200": {
+                  "content": {
+                     "application/json": {
+                        "schema": {
+                           "properties": {
+                              "items": {
+                                 "items": {
+                                    "$ref": "#/components/schemas/DeploymentVersion"
+                                 },
+                                 "type": "array"
+                              },
+                              "limit": {
+                                 "description": "Maximum number of items returned",
+                                 "type": "integer"
+                              },
+                              "offset": {
+                                 "description": "Number of items skipped",
+                                 "type": "integer"
+                              },
+                              "total": {
+                                 "description": "Total number of items available",
+                                 "type": "integer"
+                              }
+                           },
+                           "required": [
+                              "items",
+                              "total",
+                              "limit",
+                              "offset"
+                           ],
+                           "type": "object"
+                        }
+                     }
+                  },
+                  "description": "Eligible versions for the release target"
+               },
+               "400": {
+                  "content": {
+                     "application/json": {
+                        "schema": {
+                           "$ref": "#/components/schemas/ErrorResponse"
+                        }
+                     }
+                  },
+                  "description": "Invalid request"
+               },
+               "404": {
+                  "content": {
+                     "application/json": {
+                        "schema": {
+                           "$ref": "#/components/schemas/ErrorResponse"
+                        }
+                     }
+                  },
+                  "description": "Resource not found"
+               }
+            },
+            "summary": "List versions eligible for a release target"
+         }
+      },
       "/v1/workspaces/{workspaceId}/release-targets/{releaseTargetKey}/jobs": {
          "get": {
             "description": "Returns a list of jobs for a release target {releaseTargetKey}.",

apps/api/openapi/paths/release-targets.jsonnet

@@ -90,6 +90,39 @@ local openapi = import '../lib/openapi.libsonnet';
     },
   },
 
+  '/v1/workspaces/{workspaceId}/release-targets/{releaseTargetKey}/eligible-versions': {
+    post: {
+      summary: 'List versions eligible for a release target',
+      operationId: 'listEligibleVersionsForReleaseTarget',
+      description: 'Returns deployment versions that currently pass every policy rule for this release target. An optional CEL filter narrows the result; pagination is applied to the filtered set. Use the "version" variable in the CEL expression to access version properties.',
+      parameters: [
+        openapi.workspaceIdParam(),
+        openapi.releaseTargetKeyParam(),
+        openapi.limitParam(),
+        openapi.offsetParam(),
+      ],
+      requestBody: {
+        required: true,
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: {
+                filter: {
+                  type: 'string',
+                  description: 'CEL expression to filter eligible versions. Defaults to "true" (all eligible versions).',
+                },
+              },
+            },
+          },
+        },
+      },
+      responses: openapi.paginatedResponse(openapi.schemaRef('DeploymentVersion'), 'Eligible versions for the release target')
+                 + openapi.notFoundResponse()
+                 + openapi.badRequestResponse(),
+    },
+  },
+
   '/v1/workspaces/{workspaceId}/release-targets/resource-preview': {
     post: {
       summary: 'Preview release targets for a resource',

apps/api/src/routes/v1/workspaces/release-targets.ts

@@ -236,6 +236,34 @@ const getReleaseTargetState: AsyncTypedHandler<
   res.status(200).json(data);
 };
 
+const listEligibleVersionsForReleaseTarget: AsyncTypedHandler<
+  "/v1/workspaces/{workspaceId}/release-targets/{releaseTargetKey}/eligible-versions",
+  "post"
+> = async (req, res) => {
+  const { workspaceId, releaseTargetKey } = req.params;
+  const { limit, offset } = req.query;
+  const { filter } = req.body;
+
+  const { data, error, response } = await getClientFor(workspaceId).POST(
+    "/v1/workspaces/{workspaceId}/release-targets/{releaseTargetKey}/eligible-versions",
+    {
+      params: {
+        path: { workspaceId, releaseTargetKey },
+        query: { limit, offset },
+      },
+      body: { filter },
+    },
+  );
+
+  if (error != null)
+    throw new ApiError(
+      error.error ?? "Failed to list eligible versions",
+      response.status >= 400 && response.status < 500 ? response.status : 502,
+    );
+
+  res.status(200).json(data);
+};
+
 const getReleaseTargetStates: AsyncTypedHandler<
   "/v1/workspaces/{workspaceId}/release-targets/state",
   "post"
@@ -436,7 +464,11 @@ const previewReleaseTargetsForResource: AsyncTypedHandler<
 const releaseTargetKeyRouter = Router({ mergeParams: true })
   .get("/jobs", asyncHandler(getReleaseTargetJobs))
   .get("/desired-release", asyncHandler(getReleaseTargetDesiredRelease))
-  .get("/state", asyncHandler(getReleaseTargetState));
+  .get("/state", asyncHandler(getReleaseTargetState))
+  .post(
+    "/eligible-versions",
+    asyncHandler(listEligibleVersionsForReleaseTarget),
+  );
 
 export const releaseTargetsRouter = Router({ mergeParams: true })
   .post("/state", asyncHandler(getReleaseTargetStates))

apps/api/src/types/openapi.ts

@@ -655,6 +655,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/workspaces/{workspaceId}/release-targets/{releaseTargetKey}/eligible-versions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * List versions eligible for a release target
+         * @description Returns deployment versions that currently pass every policy rule for this release target. An optional CEL filter narrows the result; pagination is applied to the filtered set. Use the "version" variable in the CEL expression to access version properties.
+         */
+        post: operations["listEligibleVersionsForReleaseTarget"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/workspaces/{workspaceId}/release-targets/{releaseTargetKey}/jobs": {
         parameters: {
             query?: never;
@@ -4984,6 +5004,69 @@ export interface operations {
             };
         };
     };
+    listEligibleVersionsForReleaseTarget: {
+        parameters: {
+            query?: {
+                /** @description Maximum number of items to return */
+                limit?: number;
+                /** @description Number of items to skip */
+                offset?: number;
+            };
+            header?: never;
+            path: {
+                /** @description ID of the workspace */
+                workspaceId: string;
+                /** @description Key of the release target */
+                releaseTargetKey: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description CEL expression to filter eligible versions. Defaults to "true" (all eligible versions). */
+                    filter?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Eligible versions for the release target */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        items: components["schemas"]["DeploymentVersion"][];
+                        /** @description Maximum number of items returned */
+                        limit: number;
+                        /** @description Number of items skipped */
+                        offset: number;
+                        /** @description Total number of items available */
+                        total: number;
+                    };
+                };
+            };
+            /** @description Invalid request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Resource not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     getJobsForReleaseTarget: {
         parameters: {
             query?: {