feat(api): add since parameter to deployment logs 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-b019e469425a59061f37c5fdc7a131a5291c66134ef0627db4f06bb1f4af0b15.yml
-openapi_spec_hash: f66a3c2efddb168db9539ba2507b10b8
-config_hash: aae6721b2be9ec8565dfc8f7eadfe105
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-2aec229ccf91f7c1ac95aa675ea2a59bd61af9e363a22c3b49677992f1eeb16a.yml
+openapi_spec_hash: c80cd5d52a79cd5366a76d4a825bd27a
+config_hash: b8e1fff080fbaa22656ab0a57b591777

api.md

@@ -5,6 +5,7 @@ Types:
 - <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>
+- <code><a href="./src/resources/shared.ts">HeartbeatEvent</a></code>
 - <code><a href="./src/resources/shared.ts">LogEvent</a></code>
 
 # Deployments
@@ -20,7 +21,7 @@ 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/{id}/events">client.deployments.<a href="./src/resources/deployments.ts">follow</a>(id) -> DeploymentFollowResponse</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

@@ -28,6 +28,7 @@ import {
 import {
   DeploymentCreateParams,
   DeploymentCreateResponse,
+  DeploymentFollowParams,
   DeploymentFollowResponse,
   DeploymentRetrieveResponse,
   DeploymentStateEvent,
@@ -790,6 +791,7 @@ export declare namespace Kernel {
     type DeploymentRetrieveResponse as DeploymentRetrieveResponse,
     type DeploymentFollowResponse as DeploymentFollowResponse,
     type DeploymentCreateParams as DeploymentCreateParams,
+    type DeploymentFollowParams as DeploymentFollowParams,
   };
 
   export { Apps as Apps, type AppListResponse as AppListResponse, type AppListParams as AppListParams };
@@ -818,5 +820,6 @@ export declare namespace Kernel {
   export type ErrorDetail = API.ErrorDetail;
   export type ErrorEvent = API.ErrorEvent;
   export type ErrorModel = API.ErrorModel;
+  export type HeartbeatEvent = API.HeartbeatEvent;
   export type LogEvent = API.LogEvent;
 }

src/resources/apps/apps.ts

@@ -44,6 +44,11 @@ export namespace AppListResponse {
      */
     app_name: string;
 
+    /**
+     * Deployment ID
+     */
+    deployment: string;
+
     /**
      * Deployment region code
      */

src/resources/apps/deployments.ts

@@ -97,7 +97,8 @@ export namespace DeploymentCreateResponse {
 export type DeploymentFollowResponse =
   | DeploymentFollowResponse.StateEvent
   | DeploymentFollowResponse.StateUpdateEvent
-  | Shared.LogEvent;
+  | Shared.LogEvent
+  | Shared.HeartbeatEvent;
 
 export namespace DeploymentFollowResponse {
   /**

src/resources/deployments.ts

@@ -48,8 +48,13 @@ export class Deployments extends APIResource {
    * const response = await client.deployments.follow('id');
    * ```
    */
-  follow(id: string, options?: RequestOptions): APIPromise<Stream<DeploymentFollowResponse>> {
+  follow(
+    id: string,
+    query: DeploymentFollowParams | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Stream<DeploymentFollowResponse>> {
     return this._client.get(path`/deployments/${id}/events`, {
+      query,
       ...options,
       headers: buildHeaders([{ Accept: 'text/event-stream' }, options?.headers]),
       stream: true,
@@ -221,7 +226,8 @@ export type DeploymentFollowResponse =
   | Shared.LogEvent
   | DeploymentStateEvent
   | DeploymentFollowResponse.AppVersionSummaryEvent
-  | Shared.ErrorEvent;
+  | Shared.ErrorEvent
+  | Shared.HeartbeatEvent;
 
 export namespace DeploymentFollowResponse {
   /**
@@ -315,12 +321,20 @@ export interface DeploymentCreateParams {
   version?: string;
 }
 
+export interface DeploymentFollowParams {
+  /**
+   * Show logs since the given time (RFC timestamps or durations like 5m).
+   */
+  since?: string;
+}
+
 export declare namespace Deployments {
   export {
     type DeploymentStateEvent as DeploymentStateEvent,
     type DeploymentCreateResponse as DeploymentCreateResponse,
     type DeploymentRetrieveResponse as DeploymentRetrieveResponse,
     type DeploymentFollowResponse as DeploymentFollowResponse,
     type DeploymentCreateParams as DeploymentCreateParams,
+    type DeploymentFollowParams as DeploymentFollowParams,
   };
 }

src/resources/index.ts

@@ -18,6 +18,7 @@ export {
   type DeploymentRetrieveResponse,
   type DeploymentFollowResponse,
   type DeploymentCreateParams,
+  type DeploymentFollowParams,
 } from './deployments';
 export {
   Invocations,

src/resources/invocations.ts

@@ -283,7 +283,11 @@ export interface InvocationUpdateResponse {
 /**
  * Union type representing any invocation event.
  */
-export type InvocationFollowResponse = Shared.LogEvent | InvocationStateEvent | Shared.ErrorEvent;
+export type InvocationFollowResponse =
+  | Shared.LogEvent
+  | InvocationStateEvent
+  | Shared.ErrorEvent
+  | Shared.HeartbeatEvent;
 
 export interface InvocationCreateParams {
   /**

src/resources/shared.ts

@@ -48,6 +48,21 @@ export interface ErrorModel {
   inner_error?: ErrorDetail;
 }
 
+/**
+ * Heartbeat event sent periodically to keep SSE connection alive.
+ */
+export interface HeartbeatEvent {
+  /**
+   * Event type identifier (always "sse_heartbeat").
+   */
+  event: 'sse_heartbeat';
+
+  /**
+   * Time the heartbeat was sent.
+   */
+  timestamp: string;
+}
+
 /**
  * A log entry from the application.
  */

tests/api-resources/deployments.test.ts

@@ -58,4 +58,16 @@ describe('resource deployments', () => {
     expect(dataAndResponse.data).toBe(response);
     expect(dataAndResponse.response).toBe(rawResponse);
   });
+
+  // skipped: currently no good way to test endpoints with content type text/event-stream, Prism mock server will fail
+  test.skip('follow: 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.follow(
+        'id',
+        { since: '2025-06-20T12:00:00Z' },
+        { path: '/_stainless_unknown_path' },
+      ),
+    ).rejects.toThrow(Kernel.NotFoundError);
+  });
 });