@starcite/sdk 0.0.5 → 0.0.7

package/dist/index.d.cts

@@ -265,6 +265,62 @@ type TailEvent = z.infer<typeof TailEventSchema>;
  * Canonical session event surfaced by the SDK.
  */
 type SessionEvent = TailEvent;
+/**
+ * Listener dispatch phase for `session.on("event")`.
+ */
+type SessionEventPhase = "replay" | "live";
+/**
+ * Context passed to `session.on("event")` listeners.
+ */
+interface SessionEventContext {
+    /**
+     * Indicates whether this event originated from retained replay or live tail sync.
+     */
+    phase: SessionEventPhase;
+    /**
+     * Convenience flag for `phase === "replay"`.
+     */
+    replayed: boolean;
+}
+/**
+ * Session event listener signature.
+ */
+type SessionEventListener<TEvent extends SessionEvent = SessionEvent> = (event: TEvent, context: SessionEventContext) => void | Promise<void>;
+/**
+ * Item yielded by `session.tail(...)` async iterators.
+ */
+interface SessionTailItem<TEvent extends SessionEvent = SessionEvent> {
+    /**
+     * Canonical ordered event.
+     */
+    event: TEvent;
+    /**
+     * Replay/live classification for this event.
+     */
+    context: SessionEventContext;
+}
+/**
+ * Listener options for `session.on("event", ...)`.
+ */
+interface SessionOnEventOptions<TEvent extends SessionEvent = SessionEvent> {
+    /**
+     * Whether retained in-memory events should be replayed to this listener.
+     *
+     * Defaults to `true`.
+     */
+    replay?: boolean;
+    /**
+     * Optional schema used to validate and narrow events before dispatch.
+     *
+     * Schema validation failures are surfaced as session `error` events.
+     */
+    schema?: z.ZodType<TEvent>;
+}
+/**
+ * Options for async iterator tails.
+ */
+interface SessionTailIteratorOptions<TEvent extends SessionEvent = SessionEvent> extends SessionTailOptions, SessionOnEventOptions<TEvent> {
+}
 /**
  * Raw tail event batch grouped by a single WebSocket frame.
  */
@@ -300,7 +356,20 @@ interface SessionSnapshot {
 /**
  * Serializable persisted state for one session log.
  */
-interface SessionStoreState {
+interface SessionStoreMetadata {
+    /**
+     * Store payload schema version.
+     */
+    schemaVersion: 1;
+    /**
+     * Unix epoch milliseconds when this snapshot was written.
+     */
+    updatedAtMs: number;
+}
+/**
+ * Serializable persisted state for one session log.
+ */
+interface SessionStoreState<TEvent extends TailEvent = TailEvent> {
     /**
      * Highest contiguous sequence applied for this session.
      */
@@ -308,14 +377,18 @@ interface SessionStoreState {
     /**
      * Retained events snapshot used for immediate replay.
      */
-    events: TailEvent[];
+    events: TEvent[];
+    /**
+     * Optional metadata for versioning and operational introspection.
+     */
+    metadata?: SessionStoreMetadata;
 }
 /**
  * Persistence interface for session cursor + retained events.
  */
-interface SessionStore {
-    load(sessionId: string): SessionStoreState | undefined;
-    save(sessionId: string, state: SessionStoreState): void;
+interface SessionStore<TEvent extends TailEvent = TailEvent> {
+    load(sessionId: string): SessionStoreState<TEvent> | undefined;
+    save(sessionId: string, state: SessionStoreState<TEvent>): void;
     clear?(sessionId: string): void;
 }
 /**
@@ -436,7 +509,7 @@ interface SessionTailOptions {
     /**
      * Maximum time to wait for websocket handshake/open before reconnecting or failing.
      *
-     * Defaults to `4000`.
+     * Defaults to `12000`.
      */
     connectionTimeoutMs?: number;
     /**
@@ -513,38 +586,6 @@ type TailLifecycleEvent = {
     sessionId: string;
     reason: "aborted" | "caught_up" | "graceful";
 };
-/**
- * Storage adapter used by `session.consume*()` to persist the last processed cursor.
- */
-interface SessionCursorStore {
-    /**
-     * Loads the last processed cursor for a session.
-     *
-     * Return `undefined` when no cursor has been stored yet.
-     */
-    load(sessionId: string): number | undefined | Promise<number | undefined>;
-    /**
-     * Persists the last processed cursor for a session.
-     */
-    save(sessionId: string, cursor: number): void | Promise<void>;
-}
-/**
- * Durable tail consumption options with automatic cursor checkpointing.
- */
-interface SessionConsumeOptions extends Omit<SessionTailOptions, "cursor"> {
-    /**
-     * Optional explicit starting cursor. When omitted, the SDK loads it from `cursorStore`.
-     */
-    cursor?: number;
-    /**
-     * Cursor storage adapter used for resume-safe processing.
-     */
-    cursorStore: SessionCursorStore;
-    /**
-     * Event handler. The cursor is checkpointed only after this handler succeeds.
-     */
-    handler: (event: TailEvent) => void | Promise<void>;
-}
 /**
  * Options for listing sessions.
  */
@@ -627,9 +668,9 @@ interface StarciteOptions {
      */
     websocketFactory?: StarciteWebSocketFactory;
     /**
-     * Session store used for cursor + retained event persistence.
+     * Optional session store used for cursor + retained event persistence.
      *
-     * Defaults to an in-memory store.
+     * When omitted, fresh attaches start from cursor `0` and replay from server tail.
      */
     store?: SessionStore;
 }
@@ -747,7 +788,7 @@ declare class SessionLog {
         replay?: boolean;
     }): () => void;
     private apply;
-    getSnapshot(syncing: boolean): SessionSnapshot;
+    state(syncing: boolean): SessionSnapshot;
     get events(): readonly TailEvent[];
     get cursor(): number;
     get lastSeq(): number;
@@ -777,11 +818,10 @@ interface StarciteSessionOptions {
     token: string;
     identity: StarciteIdentity;
     transport: TransportConfig;
-    store: SessionStore;
+    store?: SessionStore;
     record?: SessionRecord;
     logOptions?: SessionLogOptions;
 }
-type SessionEventListener = (event: SessionEvent) => void;
 /**
  * Session-scoped client bound to a specific identity and session token.
  *
@@ -803,8 +843,10 @@ declare class StarciteSession {
     private readonly store;
     private readonly lifecycle;
     private readonly eventSubscriptions;
+    private appendTask;
     private liveSyncController;
     private liveSyncTask;
+    private liveSyncCatchUpActive;
     constructor(options: StarciteSessionOptions);
     /**
      * Appends an event to this session.
@@ -820,6 +862,7 @@ declare class StarciteSession {
      * Subscribes to canonical session events and lifecycle errors.
      */
     on(eventName: "event", listener: SessionEventListener): () => void;
+    on<TEvent extends SessionEvent>(eventName: "event", listener: SessionEventListener<TEvent>, options: SessionOnEventOptions<TEvent>): () => void;
     on(eventName: "error", listener: (error: Error) => void): () => void;
     /**
      * Removes a previously registered listener.
@@ -839,25 +882,32 @@ declare class StarciteSession {
      */
     setLogOptions(options: SessionLogOptions): void;
     /**
-     * Returns a stable snapshot of the current canonical in-memory log.
+     * Returns a stable view of the current canonical in-memory log state.
      */
-    getSnapshot(): SessionSnapshot;
+    state(): SessionSnapshot;
     /**
-     * Streams tail events one at a time via callback.
+     * Returns the retained canonical event list.
      */
-    tail(onEvent: (event: TailEvent) => void | Promise<void>, options?: SessionTailOptions): Promise<void>;
+    events(): readonly SessionEvent[];
     /**
-     * Streams tail event batches grouped by incoming frame via callback.
-     */
-    tailBatches(onBatch: (batch: TailEvent[]) => void | Promise<void>, options?: SessionTailOptions): Promise<void>;
-    /**
-     * Durably consumes events and checkpoints `event.seq` after each successful handler invocation.
+     * Streams canonical events as an async iterator.
+     *
+     * Replay semantics and schema validation mirror `session.on("event", ...)`.
      */
-    consume(options: SessionConsumeOptions): Promise<void>;
+    tail<TEvent extends SessionEvent = SessionEvent>(options?: SessionTailIteratorOptions<TEvent>): AsyncIterable<SessionTailItem<TEvent>>;
+    private parseOnEvent;
+    private parseTailEvent;
+    private resolveEventContext;
+    private observeEventListenerResult;
+    private createTailAbortController;
+    private createTailRuntime;
+    private iterateLiveTail;
     private emitStreamError;
     private ensureLiveSync;
     private runLiveSync;
+    private subscribeLiveSyncPass;
     private persistLogState;
+    private waitForLiveSyncRetry;
 }
 
 /**
@@ -890,7 +940,7 @@ declare class Starcite {
      * Creates or binds to a session.
      *
      * **With identity** (backend): creates a new session and/or mints a session
-     * token for the given identity. Pass `id` to bind to an existing session.
+     * token for the given identity. Pass `id` to create-or-bind that session.
      *
      * **With token** (frontend): wraps an existing session token. The identity
      * and session id are decoded from the JWT.
@@ -919,16 +969,17 @@ declare class Starcite {
 }
 
 /**
- * Minimal Web Storage contract used by {@link WebStorageCursorStore}.
+ * Minimal Web Storage contract used by {@link WebStorageSessionStore}.
  */
 interface StarciteWebStorage {
     getItem(key: string): string | null;
     setItem(key: string, value: string): void;
+    removeItem?(key: string): void;
 }
 /**
- * Key customization options for storage-backed cursor stores.
+ * Key customization options for storage-backed session stores.
  */
-interface CursorStoreOptions {
+interface SessionStoreOptions {
     /**
      * Prefix used when deriving storage keys.
      *
@@ -941,42 +992,45 @@ interface CursorStoreOptions {
     keyForSession?: (sessionId: string) => string;
 }
 /**
- * In-memory cursor store (useful for workers/tests).
+ * Construction options for {@link WebStorageSessionStore}.
  */
-declare class InMemoryCursorStore implements SessionCursorStore {
-    private readonly cursors;
-    constructor(initial?: Record<string, number>);
-    load(sessionId: string): number | undefined;
-    save(sessionId: string, cursor: number): void;
-}
-/**
- * Cursor store backed by a Web Storage-compatible object.
- */
-declare class WebStorageCursorStore implements SessionCursorStore {
-    private readonly storage;
-    private readonly keyForSession;
-    constructor(storage: StarciteWebStorage, options?: CursorStoreOptions);
-    load(sessionId: string): number | undefined;
-    save(sessionId: string, cursor: number): void;
+interface WebStorageSessionStoreOptions<TEvent extends TailEvent = TailEvent> extends SessionStoreOptions {
+    /**
+     * Optional schema for validating persisted state payloads.
+     *
+     * When omitted, a default schema validates canonical TailEvent snapshots.
+     */
+    stateSchema?: z.ZodType<SessionStoreState<TEvent>>;
 }
-/**
- * Cursor store backed by `globalThis.localStorage`.
- */
-declare class LocalStorageCursorStore extends WebStorageCursorStore {
-    constructor(options?: CursorStoreOptions);
-}
-
 /**
  * Default in-memory session store.
  *
  * Persists both cursor and retained events for each session so late subscribers
  * can replay immediately after process-local reconnect/rebind.
  */
-declare class MemoryStore implements SessionStore {
+declare class MemoryStore<TEvent extends TailEvent = TailEvent> implements SessionStore<TEvent> {
     private readonly sessions;
-    load(sessionId: string): SessionStoreState | undefined;
-    save(sessionId: string, state: SessionStoreState): void;
+    load(sessionId: string): SessionStoreState<TEvent> | undefined;
+    save(sessionId: string, state: SessionStoreState<TEvent>): void;
+    clear(sessionId: string): void;
+}
+/**
+ * Session store backed by a Web Storage-compatible object.
+ */
+declare class WebStorageSessionStore<TEvent extends TailEvent = TailEvent> implements SessionStore<TEvent> {
+    private readonly storage;
+    private readonly keyForSession;
+    private readonly stateSchema;
+    constructor(storage: StarciteWebStorage, options?: WebStorageSessionStoreOptions<TEvent>);
+    load(sessionId: string): SessionStoreState<TEvent> | undefined;
+    save(sessionId: string, state: SessionStoreState<TEvent>): void;
     clear(sessionId: string): void;
 }
+/**
+ * Session store backed by `globalThis.localStorage`.
+ */
+declare class LocalStorageSessionStore<TEvent extends TailEvent = TailEvent> extends WebStorageSessionStore<TEvent> {
+    constructor(options?: WebStorageSessionStoreOptions<TEvent>);
+}
 
-export { type AppendEventRequest, type AppendEventResponse, type AppendResult, type CursorStoreOptions, InMemoryCursorStore, LocalStorageCursorStore, MemoryStore, type PrincipalType, type RequestOptions, type SessionAppendInput, type SessionConsumeOptions, type SessionCursorStore, type SessionEvent, type SessionListItem, type SessionListOptions, type SessionListPage, SessionLogConflictError, SessionLogGapError, type SessionLogOptions, type SessionRecord, type SessionSnapshot, type SessionStore, type SessionStoreState, type SessionTailOptions, type SessionTokenScope, Starcite, StarciteApiError, StarciteBackpressureError, StarciteConnectionError, StarciteError, StarciteIdentity, type StarciteOptions, StarciteRetryLimitError, StarciteSession, StarciteTailError, type StarciteTailErrorStage, StarciteTokenExpiredError, type StarciteWebSocket, type StarciteWebSocketCloseEvent, type StarciteWebSocketEventMap, type StarciteWebSocketFactory, type StarciteWebSocketMessageEvent, type StarciteWebStorage, type TailEvent, type TailEventBatch, type TailLifecycleEvent, type TailReconnectPolicy, WebStorageCursorStore };
+export { type AppendEventRequest, type AppendEventResponse, type AppendResult, LocalStorageSessionStore, MemoryStore, type PrincipalType, type RequestOptions, type SessionAppendInput, type SessionEvent, type SessionEventContext, type SessionEventListener, type SessionEventPhase, type SessionListItem, type SessionListOptions, type SessionListPage, SessionLogConflictError, SessionLogGapError, type SessionLogOptions, type SessionOnEventOptions, type SessionRecord, type SessionSnapshot, type SessionStore, type SessionStoreMetadata, type SessionStoreOptions, type SessionStoreState, type SessionTailItem, type SessionTailIteratorOptions, type SessionTailOptions, type SessionTokenScope, Starcite, StarciteApiError, StarciteBackpressureError, StarciteConnectionError, StarciteError, StarciteIdentity, type StarciteOptions, StarciteRetryLimitError, StarciteSession, StarciteTailError, type StarciteTailErrorStage, StarciteTokenExpiredError, type StarciteWebSocket, type StarciteWebSocketCloseEvent, type StarciteWebSocketEventMap, type StarciteWebSocketFactory, type StarciteWebSocketMessageEvent, type StarciteWebStorage, type TailEvent, type TailEventBatch, type TailLifecycleEvent, type TailReconnectPolicy, WebStorageSessionStore, type WebStorageSessionStoreOptions };