docs: document SSE metadata access in generated SDKs#5998
Open
fern-api[bot] wants to merge 11 commits into
Open
docs: document SSE metadata access in generated SDKs#5998fern-api[bot] wants to merge 11 commits into
fern-api[bot] wants to merge 11 commits into
Conversation
…rated SDKs Add Server-sent events section to SDK user features page documenting: - Default streaming iteration (TypeScript, Python) - SSE metadata access via .withMetadata() (TypeScript) and RecvEvent() (Go) - ServerSentEvent fields: id, data, event, retry - Stream resumption with event ID and Last-Event-ID header - Backward compatibility Cross-reference from OpenAPI and Fern Definition SSE pages. Update capabilities page to link to SDK-side SSE docs. Co-Authored-By: bot_apk <apk@cognition.ai>
Contributor
Author
|
Requested by: devin.logan |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| ``` | ||
|
|
||
| <Note> | ||
| For SDK-side usage of SSE metadata (event ID, event type, retry interval), see [Accessing SSE metadata](/learn/sdks/deep-dives/sdk-user-features#accessing-sse-metadata). |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SSE' has no definition.
| ``` | ||
|
|
||
| <Note> | ||
| For SDK-side usage of SSE metadata (event ID, event type, retry interval), see [Accessing SSE metadata](/learn/sdks/deep-dives/sdk-user-features#accessing-sse-metadata). |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SSE' has no definition.
| ``` | ||
|
|
||
| <Note> | ||
| For SDK-side usage of SSE metadata (event ID, event type, retry interval), see [Accessing SSE metadata](/learn/sdks/deep-dives/sdk-user-features#accessing-sse-metadata). |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SSE' has no definition.
| ``` | ||
|
|
||
| <Note> | ||
| For SDK-side usage of SSE metadata (event ID, event type, retry interval), see [Accessing SSE metadata](/learn/sdks/deep-dives/sdk-user-features#accessing-sse-metadata). |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SSE' has no definition.
| - **Webhook signature verification**: Verify the signature of incoming webhook requests. [Learn more](/learn/sdks/deep-dives/webhook-signature-verification) | ||
| - **Idempotency headers**: Built-in protection against duplicate submissions. [Learn more](/sdks/deep-dives/idempotency) | ||
| - **Server-sent events**: Stream JSON data from your server to your client. [Learn more](/api-definitions/openapi/endpoints/sse) | ||
| - **Server-sent events**: Stream JSON data from your server to your client, with opt-in access to SSE metadata (event ID, event type, retry). [Learn more](/learn/sdks/deep-dives/sdk-user-features#server-sent-events) |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SSE' has no definition.
| </CodeBlock> | ||
| </CodeBlocks> | ||
|
|
||
| ### Accessing SSE metadata |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Accessing SSE metadata' should use sentence-style capitalization.
| </CodeBlock> | ||
| </CodeBlocks> | ||
|
|
||
| ### Accessing SSE metadata |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SSE' has no definition.
|
|
||
| ### Accessing SSE metadata | ||
|
|
||
| To access SSE protocol fields (event ID, event type, retry interval) alongside the parsed data, use the metadata-aware iteration methods: |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SSE' has no definition.
| </CodeBlock> | ||
| </CodeBlocks> | ||
|
|
||
| This is useful for capturing the event ID to resume a stream later via the standard SSE `Last-Event-ID` header. Store the last received ID as you iterate, then pass it back to the server on reconnection. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SSE' has no definition.
Contributor
|
🌿 Preview your docs: https://fern-preview-devin-1782499352-sse-metadata-docs.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
- Add Go tab to default iteration code block (stream.Recv pattern) - Add Python tab to metadata code block with note that metadata access is not yet available in Python - Rename heading to 'Accessing server-sent event metadata' for clarity - Update cross-reference links to match new anchor - Define SSE in-context as 'server-sent event (SSE)' in cross-refs - Add SSE to Vale Acronyms and Headings exception lists - Update Note to clarify Python support status Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
| </CodeBlock> | ||
| <CodeBlock title="Python"> | ||
| ```python | ||
| # Python does not yet expose SSE metadata to callers. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'doesn't' instead of 'does not'.
| Default iteration is unchanged, so these methods are fully backward compatible. | ||
|
|
||
| <Note> | ||
| Metadata access requires TypeScript SDK generator version 3.73.0+ or Go SDK generator version 1.32.0+. Python support is not yet available. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.
Python SDK ships ServerSentEvent dataclass in core.http_sse with id, event, data, and retry fields. Customer thread confirms users import and use this class directly. Updated docs to include Python alongside TypeScript (withMetadata) and Go (RecvEvent) rather than stating Python support is not yet available. Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
- New page at deep-dives/sse-metadata.mdx with code blocks for TypeScript (withMetadata), Go (RecvEvent), and Python (ServerSentEvent) - sdk-user-features SSE section reduced to one-liner + link - Navigation YAML updated with new page in SDK design section - Cross-references updated: OpenAPI SSE, Fern Definition SSE, capabilities page all point to new canonical page Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
Python does not have a high-level metadata iteration API (no withMetadata/RecvEvent equivalent). The ServerSentEvent class exists in core.http_sse but the generated client only surfaces parsed data. Only show TypeScript and Go in the metadata-aware iteration block. Also adds ## Default iteration heading for section symmetry. Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
- Changed 'Python SDKs support default iteration only' to 'Python does not yet expose an equivalent method' — accurate without implying the metadata is unreachable (ServerSentEvent exists in core.http_sse) - Removed 'TypeScript and Go' from prose sentence to avoid restating what the Note already covers Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
…on section Co-Authored-By: Devin Logan <devinannlogan@gmail.com>
devalog
approved these changes
Jun 27, 2026
fern-support
approved these changes
Jun 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds documentation for accessing SSE protocol metadata (event ID, event type, retry interval) in generated SDKs.
New "Server-sent events" section in
generated-sdk.mdx(SDK user features):stream.withMetadata()(TS >= 3.73.0) andstream.RecvEvent()/stream.LastEventID()(Go >= 1.32.0)Last-Event-IDheaderAll three languages (TypeScript, Python, Go) appear in both code blocks for tab consistency. Verified against generator source:
Stream[T].Recv()for data,Stream[T].RecvEvent()forStreamEvent[T]withSseEventMeta(ID,Event,Retry)EventSource.iter_sse()yieldsServerSentEventinternally but generated client methods only expose parsed data — no user-facing metadata API yetstream.withMetadata()→AsyncIterable<ServerSentEvent<T>>Cross-references added from OpenAPI SSE page, Fern Definition SSE page, and SDK capabilities page. SSE added to Vale
Acronyms.ymlandHeadings.ymlexception lists.Requested by: Fern Support
Link to Devin session: https://app.devin.ai/sessions/24f08a389b784ac297acec6909e82bf2