feat: Add explicit SSE event names for local v3 streaming

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 8
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-975ca868b31b1e45fb00b31a53d9df1ceec8663f6c2851bf40fdaa84171afadc.yml
-openapi_spec_hash: 37891379e0f47e5c69769fbaa1064dab
-config_hash: 0209737a4ab2a71afececb0ff7459998
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-a4a5ea048bb50d06460d81d6828b53b12b19e9224121ee6338dcd1f0781e22a1.yml
+openapi_spec_hash: 9b81c0ae04576318d13d7a80d4ab7b5a
+config_hash: d6c6f623d03971bdba921650e5eb7e5f

stagehand-java-core/src/main/kotlin/com/browserbase/api/core/handlers/SseHandler.kt

@@ -18,23 +18,11 @@ import com.fasterxml.jackson.module.kotlin.jacksonTypeRef
 internal fun sseHandler(jsonMapper: JsonMapper): Handler<StreamResponse<SseMessage>> =
     streamHandler { response, lines ->
         val state = SseState(jsonMapper)
-        var done = false
         for (line in lines) {
-            // Stop emitting messages, but iterate through the full stream.
-            if (done) {
-                continue
-            }
-
             val message = state.decode(line) ?: continue
 
-            when {
-                message.data.startsWith("{\"data\":{\"status\":\"finished\"") -> {
-                    // In this case we don't break because we still want to iterate through the full
-                    // stream.
-                    done = true
-                    continue
-                }
-                message.data.startsWith("error") -> {
+            when (message.event) {
+                "error" -> {
                     throw SseException.builder()
                         .statusCode(response.statusCode())
                         .headers(response.headers())
@@ -47,10 +35,10 @@ internal fun sseHandler(jsonMapper: JsonMapper): Handler<StreamResponse<SseMessa
                         )
                         .build()
                 }
-            }
-
-            if (message.event == null) {
-                yield(message)
+                "starting",
+                "connected",
+                "running",
+                "finished" -> yield(message)
             }
         }
     }

stagehand-java-core/src/main/kotlin/com/browserbase/api/models/sessions/StreamEvent.kt

@@ -30,8 +30,8 @@ import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
 /**
- * Server-Sent Event emitted during streaming responses. Events are sent as `data: <JSON>\n\n`. Key
- * order: data (with status first), type, id.
+ * Server-Sent Event emitted during streaming responses. Events are sent as `event: <status>\ndata:
+ * <JSON>\n\n`, where the JSON payload has the shape `{ data, type, id }`.
  */
 class StreamEvent
 @JsonCreator(mode = JsonCreator.Mode.DISABLED)

stagehand-java-core/src/test/kotlin/com/browserbase/api/core/handlers/SseHandlerTest.kt

@@ -2,10 +2,12 @@
 
 package com.browserbase.api.core.handlers
 
+import com.browserbase.api.core.JsonValue
 import com.browserbase.api.core.http.Headers
 import com.browserbase.api.core.http.HttpResponse
 import com.browserbase.api.core.http.SseMessage
 import com.browserbase.api.core.jsonMapper
+import com.browserbase.api.errors.SseException
 import java.io.InputStream
 import java.util.stream.Collectors.toList
 import org.assertj.core.api.Assertions.assertThat
@@ -21,64 +23,105 @@ internal class SseHandlerTest {
         internal val expectedMessages: List<SseMessage>? = null,
         internal val expectedException: Exception? = null,
     ) {
-        DATA_MISSING_EVENT(
+        EVENT_AND_DATA(
             buildString {
+                append("event: starting\n")
                 append("data: {\"foo\":true}\n")
                 append("\n")
             },
-            listOf(sseMessageBuilder().data("{\"foo\":true}").build()),
+            listOf(sseMessageBuilder().event("starting").data("{\"foo\":true}").build()),
         ),
-        MULTIPLE_DATA_MISSING_EVENT(
+        EVENT_MISSING_DATA(
             buildString {
+                append("event: starting\n")
+                append("\n")
+            },
+            listOf(sseMessageBuilder().event("starting").build()),
+        ),
+        MULTIPLE_EVENTS_AND_DATA(
+            buildString {
+                append("event: starting\n")
                 append("data: {\"foo\":true}\n")
                 append("\n")
+                append("event: connected\n")
                 append("data: {\"bar\":false}\n")
                 append("\n")
             },
             listOf(
-                sseMessageBuilder().data("{\"foo\":true}").build(),
-                sseMessageBuilder().data("{\"bar\":false}").build(),
+                sseMessageBuilder().event("starting").data("{\"foo\":true}").build(),
+                sseMessageBuilder().event("connected").data("{\"bar\":false}").build(),
+            ),
+        ),
+        MULTIPLE_EVENTS_MISSING_DATA(
+            buildString {
+                append("event: starting\n")
+                append("\n")
+                append("event: connected\n")
+                append("\n")
+            },
+            listOf(
+                sseMessageBuilder().event("starting").build(),
+                sseMessageBuilder().event("connected").build(),
             ),
         ),
         DATA_JSON_ESCAPED_DOUBLE_NEW_LINE(
             buildString {
+                append("event: starting\n")
                 append("data: {\n")
                 append("data: \"foo\":\n")
                 append("data: true}\n")
                 append("\n\n")
             },
-            listOf(sseMessageBuilder().data("{\n\"foo\":\ntrue}").build()),
+            listOf(sseMessageBuilder().event("starting").data("{\n\"foo\":\ntrue}").build()),
         ),
         MULTIPLE_DATA_LINES(
             buildString {
+                append("event: starting\n")
                 append("data: {\n")
                 append("data: \"foo\":\n")
                 append("data: true}\n")
                 append("\n\n")
             },
-            listOf(sseMessageBuilder().data("{\n\"foo\":\ntrue}").build()),
+            listOf(sseMessageBuilder().event("starting").data("{\n\"foo\":\ntrue}").build()),
         ),
         SPECIAL_NEW_LINE_CHARACTER(
             buildString {
+                append("event: starting\n")
                 append("data: {\"content\":\" culpa\"}\n")
                 append("\n")
+                append("event: connected\n")
                 append("data: {\"content\":\" \u2028\"}\n")
                 append("\n")
+                append("event: starting\n")
                 append("data: {\"content\":\"foo\"}\n")
                 append("\n")
             },
             listOf(
-                sseMessageBuilder().data("{\"content\":\" culpa\"}").build(),
-                sseMessageBuilder().data("{\"content\":\" \u2028\"}").build(),
-                sseMessageBuilder().data("{\"content\":\"foo\"}").build(),
+                sseMessageBuilder().event("starting").data("{\"content\":\" culpa\"}").build(),
+                sseMessageBuilder().event("connected").data("{\"content\":\" \u2028\"}").build(),
+                sseMessageBuilder().event("starting").data("{\"content\":\"foo\"}").build(),
             ),
         ),
         MULTI_BYTE_CHARACTER(
             buildString {
+                append("event: starting\n")
                 append("data: {\"content\":\"\u0438\u0437\u0432\u0435\u0441\u0442\u043d\u0438\"}\n")
                 append("\n")
             },
-            listOf(sseMessageBuilder().data("{\"content\":\"известни\"}").build()),
+            listOf(sseMessageBuilder().event("starting").data("{\"content\":\"известни\"}").build()),
+        ),
+        ERROR_EVENT(
+            buildString {
+                append("event: error\n")
+                append("data: {\"errorProperty\":\"42\"}\n")
+                append("\n")
+            },
+            expectedException =
+                SseException.builder()
+                    .statusCode(0)
+                    .headers(Headers.builder().build())
+                    .body(JsonValue.from(mapOf("errorProperty" to "42")))
+                    .build(),
         ),
     }