feat(api): add GET deployments endpoint

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 16
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-ff8ccba8b5409eaa1128df9027582cb63f66e8accd75e511f70b7c27ef26c9ae.yml
-openapi_spec_hash: 1dbacc339695a7c78718f90f791d3f01
-config_hash: b8e1fff080fbaa22656ab0a57b591777
+configured_endpoints: 17
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-2eeb61205775c5997abf8154cd6f6fe81a1e83870eff10050b17ed415aa7860b.yml
+openapi_spec_hash: 63405add4a3f53718f8183cbb8c1a22f
+config_hash: 00ec9df250b9dc077f8d3b93a442d252

api.md

@@ -2,6 +2,7 @@
 
 Types:
 
+- <code><a href="./src/resources/shared.ts">AppAction</a></code>
 - <code><a href="./src/resources/shared.ts">ErrorDetail</a></code>
 - <code><a href="./src/resources/shared.ts">ErrorEvent</a></code>
 - <code><a href="./src/resources/shared.ts">ErrorModel</a></code>
@@ -15,12 +16,14 @@ Types:
 - <code><a href="./src/resources/deployments.ts">DeploymentStateEvent</a></code>
 - <code><a href="./src/resources/deployments.ts">DeploymentCreateResponse</a></code>
 - <code><a href="./src/resources/deployments.ts">DeploymentRetrieveResponse</a></code>
+- <code><a href="./src/resources/deployments.ts">DeploymentListResponse</a></code>
 - <code><a href="./src/resources/deployments.ts">DeploymentFollowResponse</a></code>
 
 Methods:
 
 - <code title="post /deployments">client.deployments.<a href="./src/resources/deployments.ts">create</a>({ ...params }) -> DeploymentCreateResponse</code>
 - <code title="get /deployments/{id}">client.deployments.<a href="./src/resources/deployments.ts">retrieve</a>(id) -> DeploymentRetrieveResponse</code>
+- <code title="get /deployments">client.deployments.<a href="./src/resources/deployments.ts">list</a>({ ...params }) -> DeploymentListResponse</code>
 - <code title="get /deployments/{id}/events">client.deployments.<a href="./src/resources/deployments.ts">follow</a>(id, { ...params }) -> DeploymentFollowResponse</code>
 
 # Apps

src/client.ts

@@ -30,6 +30,8 @@ import {
   DeploymentCreateResponse,
   DeploymentFollowParams,
   DeploymentFollowResponse,
+  DeploymentListParams,
+  DeploymentListResponse,
   DeploymentRetrieveResponse,
   DeploymentStateEvent,
   Deployments,
@@ -789,8 +791,10 @@ export declare namespace Kernel {
     type DeploymentStateEvent as DeploymentStateEvent,
     type DeploymentCreateResponse as DeploymentCreateResponse,
     type DeploymentRetrieveResponse as DeploymentRetrieveResponse,
+    type DeploymentListResponse as DeploymentListResponse,
     type DeploymentFollowResponse as DeploymentFollowResponse,
     type DeploymentCreateParams as DeploymentCreateParams,
+    type DeploymentListParams as DeploymentListParams,
     type DeploymentFollowParams as DeploymentFollowParams,
   };
 
@@ -817,6 +821,7 @@ export declare namespace Kernel {
     type BrowserDeleteParams as BrowserDeleteParams,
   };
 
+  export type AppAction = API.AppAction;
   export type ErrorDetail = API.ErrorDetail;
   export type ErrorEvent = API.ErrorEvent;
   export type ErrorModel = API.ErrorModel;

src/resources/apps/apps.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
 import * as DeploymentsAPI from './deployments';
 import {
   DeploymentCreateParams,
@@ -39,6 +40,11 @@ export namespace AppListResponse {
      */
     id: string;
 
+    /**
+     * List of actions available on the app
+     */
+    actions: Array<Shared.AppAction>;
+
     /**
      * Name of the application
      */
@@ -49,6 +55,11 @@ export namespace AppListResponse {
      */
     deployment: string;
 
+    /**
+     * Environment variables configured for this app version
+     */
+    env_vars: { [key: string]: string };
+
     /**
      * Deployment region code
      */
@@ -58,11 +69,6 @@ export namespace AppListResponse {
      * Version label for the application
      */
     version: string;
-
-    /**
-     * Environment variables configured for this app version
-     */
-    env_vars?: { [key: string]: string };
   }
 }
 

src/resources/apps/deployments.ts

@@ -72,22 +72,13 @@ export namespace DeploymentCreateResponse {
     /**
      * List of actions available on the app
      */
-    actions: Array<App.Action>;
+    actions: Array<Shared.AppAction>;
 
     /**
      * Name of the app
      */
     name: string;
   }
-
-  export namespace App {
-    export interface Action {
-      /**
-       * Name of the action
-       */
-      name: string;
-    }
-  }
 }
 
 /**

src/resources/deployments.ts

@@ -38,6 +38,21 @@ export class Deployments extends APIResource {
     return this._client.get(path`/deployments/${id}`, options);
   }
 
+  /**
+   * List deployments. Optionally filter by application name.
+   *
+   * @example
+   * ```ts
+   * const deployments = await client.deployments.list();
+   * ```
+   */
+  list(
+    query: DeploymentListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<DeploymentListResponse> {
+    return this._client.get('/deployments', { query, ...options });
+  }
+
   /**
    * Establishes a Server-Sent Events (SSE) stream that delivers real-time logs and
    * status updates for a deployment. The stream terminates automatically once the
@@ -219,6 +234,55 @@ export interface DeploymentRetrieveResponse {
   updated_at?: string | null;
 }
 
+export type DeploymentListResponse = Array<DeploymentListResponse.DeploymentListResponseItem>;
+
+export namespace DeploymentListResponse {
+  /**
+   * Deployment record information.
+   */
+  export interface DeploymentListResponseItem {
+    /**
+     * Unique identifier for the deployment
+     */
+    id: string;
+
+    /**
+     * Timestamp when the deployment was created
+     */
+    created_at: string;
+
+    /**
+     * Deployment region code
+     */
+    region: 'aws.us-east-1a';
+
+    /**
+     * Current status of the deployment
+     */
+    status: 'queued' | 'in_progress' | 'running' | 'failed' | 'stopped';
+
+    /**
+     * Relative path to the application entrypoint
+     */
+    entrypoint_rel_path?: string;
+
+    /**
+     * Environment variables configured for this deployment
+     */
+    env_vars?: { [key: string]: string };
+
+    /**
+     * Status reason
+     */
+    status_reason?: string;
+
+    /**
+     * Timestamp when the deployment was last updated
+     */
+    updated_at?: string | null;
+  }
+}
+
 /**
  * Union type representing any deployment event.
  */
@@ -242,7 +306,7 @@ export namespace DeploymentFollowResponse {
     /**
      * List of actions available on the app
      */
-    actions: Array<AppVersionSummaryEvent.Action>;
+    actions: Array<Shared.AppAction>;
 
     /**
      * Name of the application
@@ -274,18 +338,6 @@ export namespace DeploymentFollowResponse {
      */
     env_vars?: { [key: string]: string };
   }
-
-  export namespace AppVersionSummaryEvent {
-    /**
-     * An action available on the app
-     */
-    export interface Action {
-      /**
-       * Name of the action
-       */
-      name: string;
-    }
-  }
 }
 
 export interface DeploymentCreateParams {
@@ -321,6 +373,13 @@ export interface DeploymentCreateParams {
   version?: string;
 }
 
+export interface DeploymentListParams {
+  /**
+   * Filter results by application name.
+   */
+  app_name?: string;
+}
+
 export interface DeploymentFollowParams {
   /**
    * Show logs since the given time (RFC timestamps or durations like 5m).
@@ -333,8 +392,10 @@ export declare namespace Deployments {
     type DeploymentStateEvent as DeploymentStateEvent,
     type DeploymentCreateResponse as DeploymentCreateResponse,
     type DeploymentRetrieveResponse as DeploymentRetrieveResponse,
+    type DeploymentListResponse as DeploymentListResponse,
     type DeploymentFollowResponse as DeploymentFollowResponse,
     type DeploymentCreateParams as DeploymentCreateParams,
+    type DeploymentListParams as DeploymentListParams,
     type DeploymentFollowParams as DeploymentFollowParams,
   };
 }

src/resources/index.ts

@@ -16,8 +16,10 @@ export {
   type DeploymentStateEvent,
   type DeploymentCreateResponse,
   type DeploymentRetrieveResponse,
+  type DeploymentListResponse,
   type DeploymentFollowResponse,
   type DeploymentCreateParams,
+  type DeploymentListParams,
   type DeploymentFollowParams,
 } from './deployments';
 export {

src/resources/shared.ts

@@ -1,5 +1,15 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+/**
+ * An action available on the app
+ */
+export interface AppAction {
+  /**
+   * Name of the action
+   */
+  name: string;
+}
+
 export interface ErrorDetail {
   /**
    * Lower-level error code providing more specific detail

tests/api-resources/deployments.test.ts

@@ -47,6 +47,26 @@ describe('resource deployments', () => {
     expect(dataAndResponse.response).toBe(rawResponse);
   });
 
+  // skipped: tests are disabled for the time being
+  test.skip('list', async () => {
+    const responsePromise = client.deployments.list();
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  // skipped: tests are disabled for the time being
+  test.skip('list: request options and params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(
+      client.deployments.list({ app_name: 'app_name' }, { path: '/_stainless_unknown_path' }),
+    ).rejects.toThrow(Kernel.NotFoundError);
+  });
+
   // skipped: currently no good way to test endpoints with content type text/event-stream, Prism mock server will fail
   test.skip('follow', async () => {
     const responsePromise = client.deployments.follow('id');