watchAccount()

Advanced transport adapter. Prefer createAccountSync for resource refreshes. Callbacks must complete successfully before cursor commits; propagate AbortSignal and guard late side effects. See the guide for durable cursor handling.

events workflow · All SDK methods

Import and runtime

@crisp-trade/partner-sdk/realtime — browser-safe; calls your authenticated backend, never the Partner API with secret credentials.

Client setup and shared behavior

Arguments

Argument	Presence	Released TypeScript type
`options`	Required	`WatchOptions`

Named types are expanded under “Exact released types” below. Parameters are in call order; optional does not imply nullable.

Example

Example IDs and intent keys are illustrative. Replace them with authenticated account resources and your persisted intent. Browser route names are example routes you implement on your own backend.

import { watchAccount } from '@crisp-trade/partner-sdk/realtime';
const stop = watchAccount({
  getSession: async (signal) => {
    const response = await fetch('/api/realtime/session', { signal });
    if (!response.ok) throw new Error('Session unavailable');
    return response.json();
  },
  loadCursor: async () => null, // Replay/resync from scratch in this minimal example.
  saveCursor: async () => {}, // Add account-scoped cursor storage in your adapter.
  onInvalidate: async (_event, signal) => {
    const response = await fetch('/api/account', { signal });
    if (!response.ok) throw new Error('Refresh failed');
    console.log(await response.json());
  },
  onResync: async (signal) => {
    const response = await fetch('/api/account', { signal });
    if (!response.ok) throw new Error('Resync failed');
    console.log(await response.json());
  },
});
// On logout/unmount:
stop();

Returns

The exact return type is shown below; this helper does not use the ordinary HTTP response wrapper.

Return type

() => void

Errors and lifecycle

Errors and retry policy. Financial uncertainty requires recovery with the original intent, never a new key. Realtime helpers must be stopped on logout/account switch.

Exact released types

Extracted from the shipped SDK 0.13.0, not separately maintained signatures.

Full signature

watchAccount(options: WatchOptions): () => void

WatchOptions

export interface WatchOptions {
    /** Call your authenticated BFF, never CRISP with partner credentials. */
    getSession: (signal: AbortSignal) => Promise<RealtimeSession>;
    loadCursor: (key: string, signal: AbortSignal) => Promise<string | null>;
    saveCursor: (key: string, cursor: string, signal: AbortSignal) => Promise<void>;
    onInvalidate: (event: Invalidation, signal: AbortSignal) => Promise<void>;
    onResync: (signal: AbortSignal) => Promise<void>;
    /** Optional batched delivery. Replaces onInvalidate when supplied. */
    onInvalidateBatch?: (events: readonly Invalidation[], signal: AbortSignal) => Promise<void>;
    /** Runs after each handshake, before replay callbacks. */
    onReady?: (signal: AbortSignal) => Promise<void>;
    onConnectionChange?: (state: "connecting" | "connected" | "reconnecting" | "stopped") => void;
    /** Pass signals to fetch and check before committing UI/cursor side effects. */
    signal?: AbortSignal;
    callbackTimeoutMs?: number;
    handshakeTimeoutMs?: number;
    onError?: (error: Error) => void;
    createSocket?: (endpoint: string, protocols: string[]) => Socket;
}

RealtimeSession

export type RealtimeSession = {
    endpoint: string;
    protocol: string;
    token: string;
    expiresAt: string;
    cursorKey: string;
};

Invalidation

export type Invalidation = {
    id: string;
    cursor: string;
    type: string;
    occurredAt: string;
};

Socket

type Socket = Pick<WebSocket, "addEventListener" | "send" | "close">;