///
The Quicksilver SDK leverages Server-Sent Events (SSE) to provide real-time updates and interactive capabilities, transforming traditional REST interactions into dynamic, event-driven experiences. Thi
42 views
~42 views from guests
Guest views are estimated from total page views. These include anonymous visitors and users who weren't logged in when they viewed the page.
The Quicksilver SDK leverages Server-Sent Events (SSE) to provide real-time updates and interactive capabilities, transforming traditional REST interactions into dynamic, event-driven experiences. This is crucial for applications built on programmable money, where instant feedback on transactions, stream progress, and conditional logic triggers is essential.
Instead of polling the API for updates, SSE establishes a persistent, one-way connection from the server to the client, allowing the server to push events as they occur. This is ideal for scenarios like live payment streams, monitoring agent activity, or receiving notifications when conditional logic is met.
StreamConnection ClassThe StreamConnection class (src/realtime/sse.ts) is the SDK's abstraction for managing SSE connections. It extends Node.js's EventEmitter, allowing developers to subscribe to specific real-time events.
The StreamConnection constructor takes a URL and an optional API key:
url: A URL object pointing to the specific SSE endpoint.apiKey: An optional API key. If provided, it's appended as a query parameter (api_key) to the URL for authentication.StreamConnection emits several events that you can listen for:
'open': Fired when the connection to the server is successfully established.'error': Fired when an error occurs on the connection (e.g., network issues, server-side errors). The SDK includes robust reconnection logic with exponential backoff to automatically attempt to re-establish the connection.'close': Fired when the connection is explicitly closed by calling close() or if the server terminates the connection.'stream_event': Fired when a general stream-related event occurs. The data payload conforms to the SSEStreamEvent interface.'batch_created': Fired when a new batch payment is created within an ongoing streaming transaction. The data payload conforms to the SSEBatchCreatedEvent interface.'message': A generic event for any other messages from the server that don't match stream_event or batch_created. The payload will be the raw message data (attempting JSON parsing first).close() MethodThis method explicitly closes the SSE connection, preventing further events from being received. It also emits the 'close' event.
The StreamConnection class includes built-in reconnection logic. If the connection drops unexpectedly (e.g., due to network issues), it will attempt to reconnect multiple times with an exponential backoff strategy (delay increases with each attempt, up to a maximum). You can configure the maxReconnectAttempts and reconnectDelay using respective setter methods.
The types for the real-time events are defined in src/types.ts:
SSEStreamEventRepresents a general stream status update.
SSEBatchCreatedEventRepresents a batch payment that has been processed as part of a streaming transaction.
StreamsResourceThe StreamsResource class (accessed via client.streams from the API Reference - QuicksilverClient↗) provides convenient methods to subscribe to real-time events at different scopes:
Subscribe to events related to a single streaming transaction.
Example:
Subscribe to all streaming events associated with a particular account (both incoming and outgoing streams).
Example:
Subscribe to all streaming events across the entire system that your API key has access to. This is typically used by administrators or monitoring services.
Example:
By utilizing SSE, the Quicksilver SDK empowers developers to build highly responsive and interactive applications, pushing the boundaries of programmable money into real-time agent commerce.