Events & Real-Time

The SDK provides a pub/sub event system for cross-component communication and an SSE connection for real-time updates from the server.

Event Subscription

Subscribe to events using sdk.on():

javascript

// Listen for a specific event
const unsubscribe = sdk.on('task:decided', (e) => {
  console.log('Task decided:', e.data);
});

// Unsubscribe later
unsubscribe();

Listen to all events with a wildcard:

javascript

sdk.on('*', (e) => {
  console.log(`[${e.type}]`, e.data);
});

Event Types

Component Events

Event	Data	Source
`task:created`	`{ runId, workflowName, urgency }`	New task requires attention
`task:decided`	`{ runId, stepId, approved, comment }`	Task approved or rejected via sidebar
`table:updated`	`{ table, rowId, changes }`	Row modified via data grid
`run:status`	`{ runId, status, documentId }`	Workflow run status changed

Session Events

Event	Data	Source
`authenticated`	`{ email, sessionId }`	OTP login succeeded
`session:expired`	`null`	Session token expired

System Events

Event	Data	Source
`error`	`{ message, code }`	SDK error occurred

Real-Time Updates (SSE)

Enable server-sent events for live updates across all components:

javascript

sdk.startEventStream();

When the event stream is active:

Task sidebar updates when new approval tasks are created or existing tasks are decided
Data grid reflects row changes made by workflows or other users
Doc feed shows real-time processing status as uploaded documents move through workflows

Stop the event stream:

javascript

sdk.stopEventStream();

Automatic reconnection. If the SSE connection drops (network interruption, server restart), the SDK automatically reconnects with exponential backoff. No manual intervention required.

---

SDK API Reference

`HyphenSDK.init(config)`

Initialize the SDK. Returns a promise that resolves to an SDK instance.

typescript

interface HyphenSDKConfig {
  publishableKey: string;        // Required. Your pk_live_* key.
  baseUrl?: string;              // Gateway URL. Default: '/api'
  onSessionExpired?: () => void; // Called when session expires.
}

Instance Methods

Method	Description
`sdk.login()`	Show the OTP login modal
`sdk.logout()`	Clear the current session
`sdk.getSession()`	Get the current session object
`sdk.getUser()`	Get the authenticated user (null if anonymous)
`sdk.isAuthenticated()`	Check if authenticated via OTP
`sdk.on(event, handler)`	Subscribe to SDK events. Returns unsubscribe function.
`sdk.startEventStream()`	Start real-time SSE event streaming
`sdk.stopEventStream()`	Stop event streaming
`sdk.destroy()`	Cleanup all resources (event stream, subscriptions, DOM)

Cross-Component Patterns

Upload-to-Approval Pipeline

When a document is uploaded, the triggered workflow may create approval tasks. Listen for both events to show the user the full pipeline:

javascript

sdk.on('run:status', (e) => {
  if (e.data.status === 'paused') {
    showNotification('New task waiting for your review');
  }
});

sdk.on('task:decided', (e) => {
  showNotification(`Task ${e.data.approved ? 'approved' : 'rejected'}`);
});

Refresh on External Changes

If your application modifies data outside the SDK (e.g., via direct API calls), you can refresh individual components:

javascript

// Components expose a refresh method via their DOM element
document.querySelector('hyphen-data-grid').refresh();
document.querySelector('hyphen-task-sidebar').refresh();

Cleanup

When removing SDK components from the page (e.g., navigating away in a SPA), clean up resources:

javascript

sdk.destroy();

This stops the event stream, removes all event subscriptions, and cleans up component state.