Merge branch 'main' into alberto/ts-reference-imports-ast

fern/docs.yml

@@ -147,6 +147,10 @@ navigation:
                 icon: fa-regular fa-file
                 path: ./pages/api-definition/fern-definition/endpoints/multipart.mdx
                 slug: multipart
+              - page: Server Sent Events
+                icon: fa-regular fa-signal-stream
+                path: ./pages/api-definition/fern-definition/endpoints/sse.mdx
+                slug: sse
           - page: Webhooks
             icon: fa-regular fa-webhook
             path: ./pages/api-definition/fern-definition/webhooks.mdx

fern/pages/api-definition/fern-definition/endpoints/sse.mdx

@@ -0,0 +1,101 @@
+---
+title: Server Sent Events and Streaming APIs
+subtitle: Use the `response-stream` key to model streaming endpoints
+---
+
+<Note>
+  Specifying `response-stream` on an endpoints allows you to represent endpoint responses that are streaming. 
+</Note>
+
+
+## JSON streaming
+
+If your API returns a series of `JSON` chunks as seen below
+
+```json
+{ "text": "Hi, I am a" }
+{ "text": "chatbot. Do you have any"}
+{ "text": "questions for me"}
+```
+
+then simply specify the response under `response-stream` for your endpoint. 
+
+```yaml title="chat.yml" {4}
+service:
+  base-path: /chat
+  endpoints:
+    stream:
+      method: POST
+      path: ""
+      response-stream: Chat
+
+types:
+  Chat:
+    properties:
+      text: string
+```
+
+## Server sent events 
+
+If your API returns server-sent-events, with the `data` and `event` keys as seen below
+
+```json
+data: { "text": "Hi, I am a" }
+data: { "text": "chatbot. Do you have any"}
+data: { "text": "questions for me"}
+```
+
+then make sure to include `format: sse`. 
+
+```yaml title="chat.yml" {9}
+service:
+  base-path: /chat
+  endpoints:
+    stream:
+      method: POST
+      path: ""
+      response-stream:
+        type: Chat
+        format: sse
+
+types:
+  Chat:
+    properties:
+      text: string        
+```
+
+## `Stream` parameter
+
+It has become common practice for endpoints to have a `stream` parameter that 
+controls whether the response is streamed or not. Fern supports this pattern in a first 
+class way. 
+
+Simply specify the `stream-condition` as well as the ordinary response and the streaming response: 
+
+```yaml title="chat.yml" {7}
+service:
+  base-path: /chat
+  endpoints:
+    stream:
+      method: POST
+      path: ""
+      stream-condition: $request.stream
+      request:
+        name: StreamChatRequest
+        body: 
+          properties: 
+            stream: boolean
+      response: Chat
+      response-stream:
+        type: ChatChunk
+        format: sse
+
+types:
+  Chat:
+    properties:
+      text: string
+      tokens: integer
+  ChatChunk:
+    properties:
+      text: string
+```

fern/pages/api-definition/openapi/endpoints/sse.mdx

@@ -10,7 +10,7 @@ subtitle: Use the `x-fern-streaming` extension to model streaming endpoints
 
 ## JSON streaming
 
-If you're API returns a series of `JSON` chunks as seen below
+If your API returns a series of `JSON` chunks as seen below
 
 ```json
 { "text": "Hi, I am a" }

packages/ir-sdk/fern/apis/ir-types-latest/VERSION

@@ -1 +1 @@
-53.16.0
+53.17.0

packages/ir-sdk/fern/apis/ir-types-latest/definition/dynamic/ir.yml

@@ -8,7 +8,7 @@ types:
       - dynamic
     docs: |
       This represents the IR required to generate dynamic snippets.
-      
+
       This IR minimizes the space required to generate snippets in a variety
       of environments (e.g. web, offline, etc).
     properties:

packages/ir-sdk/fern/apis/ir-types-latest/definition/dynamic/snippets.yml

@@ -4,6 +4,8 @@ imports:
 
 types:
   Values:
+    audiences:
+      - dynamic
     docs: |
       Snippet values are represented as arbitrary key, value
       pairs (i.e. JSON objects). The keys are expected to be
@@ -12,6 +14,8 @@ types:
     type: map<string, unknown>
 
   EndpointSnippetRequest:
+    audiences:
+      - dynamic
     docs: |
       The user-facing request type used to generate a dynamic snippet.
     properties:
@@ -23,6 +27,8 @@ types:
       requestBody: optional<unknown>
 
   EndpointSnippetResponse:
+    audiences:
+      - dynamic
     docs: |
       The user-facing response type containing the generated snippet.
     properties: