@gscdump/sdk 1.4.0 → 1.4.1

package/dist/v1/realtime.d.mts

@@ -0,0 +1,109 @@
+import { RealtimeV1Cursor, RealtimeV1Event, RealtimeV1StreamHead, RealtimeV1StreamId } from "@gscdump/contracts/v1";
+type MaybePromise<T> = T | Promise<T>;
+declare const GSCDUMP_REALTIME_V1_SDK_VERSION: '1.4.1';
+type GscdumpRealtimeV1TransportState = 'idle' | 'ticketing' | 'connecting' | 'handshaking' | 'replaying' | 'live' | 'waiting' | 'stopped' | 'terminal';
+type GscdumpRealtimeV1Freshness = 'unknown' | 'stale' | 'applying' | 'fresh' | 'resyncing' | 'degraded';
+type GscdumpRealtimeV1ErrorCode = 'cursor_store_failed' | 'effect_failed' | 'heartbeat_stale' | 'integration_failed' | 'protocol_error' | 'resync_failed' | 'runtime_unavailable' | 'socket_error' | 'ticket_invalid' | 'ticket_provider_failed' | 'upgrade_rejected';
+interface GscdumpRealtimeV1ErrorOptions {
+  code: GscdumpRealtimeV1ErrorCode;
+  message: string;
+  retryable: boolean;
+  terminal: boolean;
+  details?: Record<string, unknown>;
+  cause?: unknown;
+}
+declare class GscdumpRealtimeV1Error extends Error {
+  readonly tag: 'GscdumpRealtimeV1Error';
+  readonly code: GscdumpRealtimeV1ErrorCode;
+  readonly retryable: boolean;
+  readonly terminal: boolean;
+  readonly details: Record<string, unknown>;
+  readonly cause?: unknown;
+  constructor(options: GscdumpRealtimeV1ErrorOptions);
+}
+interface GscdumpRealtimeV1CursorStore {
+  load: () => MaybePromise<RealtimeV1Cursor | null>;
+  save: (cursor: RealtimeV1Cursor) => MaybePromise<void>;
+}
+interface GscdumpRealtimeV1SocketLike {
+  readonly readyState: number;
+  readonly protocol: string;
+  onopen: ((event: unknown) => void) | null;
+  onmessage: ((event: {
+    data: unknown;
+  }) => void) | null;
+  onerror: ((event: unknown) => void) | null;
+  onclose: ((event: {
+    code?: number;
+    reason?: string;
+    wasClean?: boolean;
+  }) => void) | null;
+  send: (data: string) => void;
+  close: (code?: number, reason?: string) => void;
+}
+interface GscdumpRealtimeV1Runtime {
+  createSocket: (url: string, protocols: readonly string[]) => GscdumpRealtimeV1SocketLike;
+  setTimeout: (handler: () => void, ms: number) => unknown;
+  clearTimeout: (handle: unknown) => void;
+  random: () => number;
+  now: () => number;
+}
+type GscdumpRealtimeV1ResyncReason = 'cursor_expired' | 'retention_gap' | 'sequence_gap' | 'stream_mismatch' | 'initial_cursor_missing' | 'effect_application_failed';
+interface GscdumpRealtimeV1ResyncRequest {
+  reason: GscdumpRealtimeV1ResyncReason;
+  source: 'server' | 'client';
+  streamId: RealtimeV1StreamId;
+  previousCursor: RealtimeV1Cursor | null;
+  resumeAfter: RealtimeV1Cursor;
+  failedEvent?: RealtimeV1Event;
+  cause?: unknown;
+}
+interface GscdumpRealtimeV1Snapshot {
+  transport: GscdumpRealtimeV1TransportState;
+  freshness: GscdumpRealtimeV1Freshness;
+  attempt: number;
+  streamId: RealtimeV1StreamId | null;
+  cursor: RealtimeV1Cursor | null;
+  head: RealtimeV1StreamHead | null;
+  error: GscdumpRealtimeV1Error | null;
+}
+type GscdumpRealtimeV1Observation = {
+  type: 'state';
+  state: GscdumpRealtimeV1Snapshot;
+} | {
+  type: 'event';
+  event: RealtimeV1Event;
+  cursor: RealtimeV1Cursor | null;
+} | {
+  type: 'error';
+  error: GscdumpRealtimeV1Error;
+  state: GscdumpRealtimeV1Snapshot;
+} | {
+  type: 'advisory';
+  code: 'unknown_event' | 'unknown_resource' | 'unsupported_event_version';
+  event: RealtimeV1Event;
+};
+interface CreateGscdumpRealtimeV1ClientOptions {
+  /** Called for every connection attempt. A ticket is never reused. */
+  ticketProvider: () => MaybePromise<unknown>;
+  /** Required correctness effect for each contiguous durable event. */
+  applyEvent: (event: RealtimeV1Event) => Promise<void>;
+  /** Required full authoritative reseed used whenever replay is unsafe. */
+  resync: (request: GscdumpRealtimeV1ResyncRequest) => Promise<void>;
+  cursorStore?: GscdumpRealtimeV1CursorStore;
+  /** One isolated callback for state, event, advisory, and error observations. */
+  onObservation?: (observation: GscdumpRealtimeV1Observation) => unknown;
+  runtime?: GscdumpRealtimeV1Runtime;
+  sdkVersion?: string;
+}
+interface GscdumpRealtimeV1Client {
+  start: () => Promise<void>;
+  stop: () => void;
+  getSnapshot: () => GscdumpRealtimeV1Snapshot;
+}
+/**
+ * Own the v1 cursor/ACK correctness state machine. Framework adapters provide
+ * required effects; they never need to reproduce transport ordering rules.
+ */
+declare function createGscdumpRealtimeV1Client(options: CreateGscdumpRealtimeV1ClientOptions): GscdumpRealtimeV1Client;
+export { CreateGscdumpRealtimeV1ClientOptions, GSCDUMP_REALTIME_V1_SDK_VERSION, GscdumpRealtimeV1Client, GscdumpRealtimeV1CursorStore, GscdumpRealtimeV1Error, GscdumpRealtimeV1ErrorCode, GscdumpRealtimeV1ErrorOptions, GscdumpRealtimeV1Freshness, GscdumpRealtimeV1Observation, GscdumpRealtimeV1ResyncReason, GscdumpRealtimeV1ResyncRequest, GscdumpRealtimeV1Runtime, GscdumpRealtimeV1Snapshot, GscdumpRealtimeV1SocketLike, GscdumpRealtimeV1TransportState, createGscdumpRealtimeV1Client };