Real-time Event Streaming with SSE

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.

The StreamConnection Class

The 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.

Constructor

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.

Key Event Listeners

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() Method

This method explicitly closes the SSE connection, preventing further events from being received. It also emits the 'close' event.

Reconnection Logic

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.

Event Data Interfaces

The types for the real-time events are defined in src/types.ts:

SSEStreamEvent

Represents a general stream status update.

SSEBatchCreatedEvent

Represents a batch payment that has been processed as part of a streaming transaction.

Subscribing to Events with StreamsResource

The StreamsResource class (accessed via client.streams from the API Reference - QuicksilverClient↗) provides convenient methods to subscribe to real-time events at different scopes:

1. Stream-Specific Events

Subscribe to events related to a single streaming transaction.

Example:

2. Account-Specific Events

Subscribe to all streaming events associated with a particular account (both incoming and outgoing streams).

Example:

3. Global Stream Events

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.