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

aliases.go

@@ -27,6 +27,11 @@ type ErrorEvent = shared.ErrorEvent
 // This is an alias to an internal type.
 type ErrorModel = shared.ErrorModel
 
+// Heartbeat event sent periodically to keep SSE connection alive.
+//
+// This is an alias to an internal type.
+type HeartbeatEvent = shared.HeartbeatEvent
+
 // A log entry from the application.
 //
 // This is an alias to an internal type.

api.md

@@ -3,6 +3,7 @@
 - <a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk/shared">shared</a>.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk/shared#ErrorDetail">ErrorDetail</a>
 - <a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk/shared">shared</a>.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk/shared#ErrorEvent">ErrorEvent</a>
 - <a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk/shared">shared</a>.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk/shared#ErrorModel">ErrorModel</a>
+- <a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk/shared">shared</a>.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk/shared#HeartbeatEvent">HeartbeatEvent</a>
 - <a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk/shared">shared</a>.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk/shared#LogEvent">LogEvent</a>
 
 # Deployments
@@ -18,7 +19,7 @@ Methods:
 
 - <code title="post /deployments">client.Deployments.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk#DeploymentService.New">New</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, body <a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk#DeploymentNewParams">DeploymentNewParams</a>) (<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk#DeploymentNewResponse">DeploymentNewResponse</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="get /deployments/{id}">client.Deployments.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk#DeploymentService.Get">Get</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) (<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk#DeploymentGetResponse">DeploymentGetResponse</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
-- <code title="get /deployments/{id}/events">client.Deployments.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk#DeploymentService.Follow">Follow</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) (<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk#DeploymentFollowResponseUnion">DeploymentFollowResponseUnion</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
+- <code title="get /deployments/{id}/events">client.Deployments.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk#DeploymentService.Follow">Follow</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>, query <a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk#DeploymentFollowParams">DeploymentFollowParams</a>) (<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/onkernel/kernel-go-sdk#DeploymentFollowResponseUnion">DeploymentFollowResponseUnion</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 
 # Apps
 

app.go

@@ -51,6 +51,8 @@ type AppListResponse struct {
 	ID string `json:"id,required"`
 	// Name of the application
 	AppName string `json:"app_name,required"`
+	// Deployment ID
+	Deployment string `json:"deployment,required"`
 	// Deployment region code
 	Region constant.AwsUsEast1a `json:"region,required"`
 	// Version label for the application
@@ -61,6 +63,7 @@ type AppListResponse struct {
 	JSON struct {
 		ID          respjson.Field
 		AppName     respjson.Field
+		Deployment  respjson.Field
 		Region      respjson.Field
 		Version     respjson.Field
 		EnvVars     respjson.Field

appdeployment.go

@@ -147,14 +147,15 @@ const (
 
 // AppDeploymentFollowResponseUnion contains all possible properties and values
 // from [AppDeploymentFollowResponseState],
-// [AppDeploymentFollowResponseStateUpdate], [shared.LogEvent].
+// [AppDeploymentFollowResponseStateUpdate], [shared.LogEvent],
+// [shared.HeartbeatEvent].
 //
 // Use the [AppDeploymentFollowResponseUnion.AsAny] method to switch on the
 // variant.
 //
 // Use the methods beginning with 'As' to cast the union to one of its variants.
 type AppDeploymentFollowResponseUnion struct {
-	// Any of "state", "state_update", "log".
+	// Any of "state", "state_update", "log", "sse_heartbeat".
 	Event     string    `json:"event"`
 	State     string    `json:"state"`
 	Timestamp time.Time `json:"timestamp"`
@@ -185,6 +186,7 @@ func (AppDeploymentFollowResponseStateUpdate) ImplAppDeploymentFollowResponseUni
 //	case kernel.AppDeploymentFollowResponseState:
 //	case kernel.AppDeploymentFollowResponseStateUpdate:
 //	case shared.LogEvent:
+//	case shared.HeartbeatEvent:
 //	default:
 //	  fmt.Errorf("no variant present")
 //	}
@@ -196,6 +198,8 @@ func (u AppDeploymentFollowResponseUnion) AsAny() anyAppDeploymentFollowResponse
 		return u.AsStateUpdate()
 	case "log":
 		return u.AsLog()
+	case "sse_heartbeat":
+		return u.AsSseHeartbeat()
 	}
 	return nil
 }
@@ -215,6 +219,11 @@ func (u AppDeploymentFollowResponseUnion) AsLog() (v shared.LogEvent) {
 	return
 }
 
+func (u AppDeploymentFollowResponseUnion) AsSseHeartbeat() (v shared.HeartbeatEvent) {
+	apijson.UnmarshalRoot(json.RawMessage(u.JSON.raw), &v)
+	return
+}
+
 // Returns the unmodified JSON received from the API
 func (u AppDeploymentFollowResponseUnion) RawJSON() string { return u.JSON.raw }
 

client_test.go

@@ -311,7 +311,11 @@ func TestContextDeadlineStreaming(t *testing.T) {
 				},
 			}),
 		)
-		stream := client.Deployments.FollowStreaming(deadlineCtx, "id")
+		stream := client.Deployments.FollowStreaming(
+			deadlineCtx,
+			"id",
+			kernel.DeploymentFollowParams{},
+		)
 		for stream.Next() {
 			_ = stream.Current()
 		}
@@ -359,6 +363,7 @@ func TestContextDeadlineStreamingWithRequestTimeout(t *testing.T) {
 		stream := client.Deployments.FollowStreaming(
 			context.Background(),
 			"id",
+			kernel.DeploymentFollowParams{},
 			option.WithRequestTimeout((100 * time.Millisecond)),
 		)
 		for stream.Next() {

deployment.go

@@ -11,10 +11,12 @@ import (
 	"io"
 	"mime/multipart"
 	"net/http"
+	"net/url"
 	"time"
 
 	"github.com/onkernel/kernel-go-sdk/internal/apiform"
 	"github.com/onkernel/kernel-go-sdk/internal/apijson"
+	"github.com/onkernel/kernel-go-sdk/internal/apiquery"
 	"github.com/onkernel/kernel-go-sdk/internal/requestconfig"
 	"github.com/onkernel/kernel-go-sdk/option"
 	"github.com/onkernel/kernel-go-sdk/packages/param"
@@ -66,7 +68,7 @@ func (r *DeploymentService) Get(ctx context.Context, id string, opts ...option.R
 // Establishes a Server-Sent Events (SSE) stream that delivers real-time logs and
 // status updates for a deployment. The stream terminates automatically once the
 // deployment reaches a terminal state.
-func (r *DeploymentService) FollowStreaming(ctx context.Context, id string, opts ...option.RequestOption) (stream *ssestream.Stream[DeploymentFollowResponseUnion]) {
+func (r *DeploymentService) FollowStreaming(ctx context.Context, id string, query DeploymentFollowParams, opts ...option.RequestOption) (stream *ssestream.Stream[DeploymentFollowResponseUnion]) {
 	var (
 		raw *http.Response
 		err error
@@ -78,7 +80,7 @@ func (r *DeploymentService) FollowStreaming(ctx context.Context, id string, opts
 		return
 	}
 	path := fmt.Sprintf("deployments/%s/events", id)
-	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &raw, opts...)
+	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &raw, opts...)
 	return ssestream.NewStream[DeploymentFollowResponseUnion](ssestream.NewDecoder(raw), err)
 }
 
@@ -253,13 +255,14 @@ const (
 
 // DeploymentFollowResponseUnion contains all possible properties and values from
 // [shared.LogEvent], [DeploymentStateEvent],
-// [DeploymentFollowResponseAppVersionSummaryEvent], [shared.ErrorEvent].
+// [DeploymentFollowResponseAppVersionSummaryEvent], [shared.ErrorEvent],
+// [shared.HeartbeatEvent].
 //
 // Use the [DeploymentFollowResponseUnion.AsAny] method to switch on the variant.
 //
 // Use the methods beginning with 'As' to cast the union to one of its variants.
 type DeploymentFollowResponseUnion struct {
-	// Any of "log", "deployment_state", nil, nil.
+	// Any of "log", "deployment_state", nil, nil, "sse_heartbeat".
 	Event string `json:"event"`
 	// This field is from variant [shared.LogEvent].
 	Message   string    `json:"message"`
@@ -316,6 +319,11 @@ func (u DeploymentFollowResponseUnion) AsErrorEvent() (v shared.ErrorEvent) {
 	return
 }
 
+func (u DeploymentFollowResponseUnion) AsSseHeartbeat() (v shared.HeartbeatEvent) {
+	apijson.UnmarshalRoot(json.RawMessage(u.JSON.raw), &v)
+	return
+}
+
 // Returns the unmodified JSON received from the API
 func (u DeploymentFollowResponseUnion) RawJSON() string { return u.JSON.raw }
 
@@ -423,3 +431,17 @@ type DeploymentNewParamsRegion string
 const (
 	DeploymentNewParamsRegionAwsUsEast1a DeploymentNewParamsRegion = "aws.us-east-1a"
 )
+
+type DeploymentFollowParams struct {
+	// Show logs since the given time (RFC timestamps or durations like 5m).
+	Since param.Opt[string] `query:"since,omitzero" json:"-"`
+	paramObj
+}
+
+// URLQuery serializes [DeploymentFollowParams]'s query parameters as `url.Values`.
+func (r DeploymentFollowParams) URLQuery() (v url.Values, err error) {
+	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
+		ArrayFormat:  apiquery.ArrayQueryFormatComma,
+		NestedFormat: apiquery.NestedQueryFormatBrackets,
+	})
+}

invocation.go

@@ -321,13 +321,14 @@ const (
 )
 
 // InvocationFollowResponseUnion contains all possible properties and values from
-// [shared.LogEvent], [InvocationStateEvent], [shared.ErrorEvent].
+// [shared.LogEvent], [InvocationStateEvent], [shared.ErrorEvent],
+// [shared.HeartbeatEvent].
 //
 // Use the [InvocationFollowResponseUnion.AsAny] method to switch on the variant.
 //
 // Use the methods beginning with 'As' to cast the union to one of its variants.
 type InvocationFollowResponseUnion struct {
-	// Any of "log", "invocation_state", "error".
+	// Any of "log", "invocation_state", "error", "sse_heartbeat".
 	Event string `json:"event"`
 	// This field is from variant [shared.LogEvent].
 	Message   string    `json:"message"`
@@ -361,6 +362,7 @@ func (InvocationStateEvent) ImplInvocationFollowResponseUnion() {}
 //	case shared.LogEvent:
 //	case kernel.InvocationStateEvent:
 //	case shared.ErrorEvent:
+//	case shared.HeartbeatEvent:
 //	default:
 //	  fmt.Errorf("no variant present")
 //	}
@@ -372,6 +374,8 @@ func (u InvocationFollowResponseUnion) AsAny() anyInvocationFollowResponse {
 		return u.AsInvocationState()
 	case "error":
 		return u.AsError()
+	case "sse_heartbeat":
+		return u.AsSseHeartbeat()
 	}
 	return nil
 }
@@ -391,6 +395,11 @@ func (u InvocationFollowResponseUnion) AsError() (v shared.ErrorEvent) {
 	return
 }
 
+func (u InvocationFollowResponseUnion) AsSseHeartbeat() (v shared.HeartbeatEvent) {
+	apijson.UnmarshalRoot(json.RawMessage(u.JSON.raw), &v)
+	return
+}
+
 // Returns the unmodified JSON received from the API
 func (u InvocationFollowResponseUnion) RawJSON() string { return u.JSON.raw }
 

shared/constant/constants.go

@@ -24,6 +24,7 @@ type DeploymentState string   // Always "deployment_state"
 type Error string             // Always "error"
 type InvocationState string   // Always "invocation_state"
 type Log string               // Always "log"
+type SseHeartbeat string      // Always "sse_heartbeat"
 type State string             // Always "state"
 type StateUpdate string       // Always "state_update"
 
@@ -33,6 +34,7 @@ func (c DeploymentState) Default() DeploymentState     { return "deployment_stat
 func (c Error) Default() Error                         { return "error" }
 func (c InvocationState) Default() InvocationState     { return "invocation_state" }
 func (c Log) Default() Log                             { return "log" }
+func (c SseHeartbeat) Default() SseHeartbeat           { return "sse_heartbeat" }
 func (c State) Default() State                         { return "state" }
 func (c StateUpdate) Default() StateUpdate             { return "state_update" }
 
@@ -42,6 +44,7 @@ func (c DeploymentState) MarshalJSON() ([]byte, error)   { return marshalString(
 func (c Error) MarshalJSON() ([]byte, error)             { return marshalString(c) }
 func (c InvocationState) MarshalJSON() ([]byte, error)   { return marshalString(c) }
 func (c Log) MarshalJSON() ([]byte, error)               { return marshalString(c) }
+func (c SseHeartbeat) MarshalJSON() ([]byte, error)      { return marshalString(c) }
 func (c State) MarshalJSON() ([]byte, error)             { return marshalString(c) }
 func (c StateUpdate) MarshalJSON() ([]byte, error)       { return marshalString(c) }
 

shared/shared.go

@@ -87,6 +87,30 @@ func (r *ErrorModel) UnmarshalJSON(data []byte) error {
 	return apijson.UnmarshalRoot(data, r)
 }
 
+// Heartbeat event sent periodically to keep SSE connection alive.
+type HeartbeatEvent struct {
+	// Event type identifier (always "sse_heartbeat").
+	Event constant.SseHeartbeat `json:"event,required"`
+	// Time the heartbeat was sent.
+	Timestamp time.Time `json:"timestamp,required" format:"date-time"`
+	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
+	JSON struct {
+		Event       respjson.Field
+		Timestamp   respjson.Field
+		ExtraFields map[string]respjson.Field
+		raw         string
+	} `json:"-"`
+}
+
+// Returns the unmodified JSON received from the API
+func (r HeartbeatEvent) RawJSON() string { return r.JSON.raw }
+func (r *HeartbeatEvent) UnmarshalJSON(data []byte) error {
+	return apijson.UnmarshalRoot(data, r)
+}
+
+func (HeartbeatEvent) ImplAppDeploymentFollowResponseUnion() {}
+func (HeartbeatEvent) ImplInvocationFollowResponseUnion()    {}
+
 // A log entry from the application.
 type LogEvent struct {
 	// Event type identifier (always "log").