@nemphi/sdk 0.2.5277 → 0.3.5324

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -577,9 +577,9 @@ export interface Notification {
577
577
  seq?: number;
578
578
  }
579
579
  /**
580
- * One realtime event of the workspace (`openRealtimeSocket`, which polls
581
- * `GET /v1/events/poll`; the frames of `GET /v1/events/stream` and
582
- * `GET /v1/events/socket`).
580
+ * One realtime event of the workspace (`openRealtimeSocket` and
581
+ * `streamEvents`, the frames of `GET /v1/events/stream` and
582
+ * `GET /v1/events/socket`), or of one chat thread (`streamThread`).
583
583
  * `action` and `notification` are wakeups — re-read the surface, the row
584
584
  * itself comes by cursor; the rest is state that only matters while
585
585
  * someone is watching.
@@ -653,6 +653,13 @@ export type RealtimeEvent = {
653
653
  /** ISO instant after which a reader drops them unless the signal repeats. */
654
654
  until: string;
655
655
  };
656
+ /**
657
+ * One frame of a chat thread's own stream (`streamThread`): a piece of the
658
+ * answer a run is writing (`run_delta`), or a run step's end (`run`).
659
+ */
660
+ export type ThreadStreamEvent = Extract<RealtimeEvent, {
661
+ type: "run" | "run_delta";
662
+ }>;
656
663
  /** Where a person is typing: a chat thread or a marketing inbox conversation. */
657
664
  export type TypingScope = Extract<RealtimeEvent, {
658
665
  type: "typing";
@@ -671,7 +678,7 @@ export interface RealtimeSocketOptions {
671
678
  /** Called when a poll fails after one answered. */
672
679
  onClose?: () => void;
673
680
  /**
674
- * Ignored: the subscription polls `GET /v1/events/poll` over `fetch`
681
+ * Ignored: the subscription reads `GET /v1/events/stream` over `fetch`
675
682
  * rather than holding a WebSocket. Kept so existing callers compile.
676
683
  */
677
684
  webSocket?: (url: string, headers: Record<string, string>) => WebSocket;
@@ -8694,22 +8701,48 @@ export interface NemphiClient {
8694
8701
  next_before?: number;
8695
8702
  }>;
8696
8703
  /**
8697
- * Live tail of the action ledger (`GET /v1/events/stream`, SSE).
8698
- * Resumes from `cursor` (last seen action id); abort via `signal`.
8704
+ * One connection to the workspace's realtime stream
8705
+ * (`GET /v1/events/stream`, server-sent events): every frame it carries,
8706
+ * checked by its `type`, until the connection ends (the server closes a
8707
+ * stream after 15 minutes) or `signal` aborts. `action` and
8708
+ * `notification` are wake-ups naming a row; read the row back. The
8709
+ * stream keeps no position, so a reader that connects again re-reads
8710
+ * what it shows. `openRealtimeSocket` reconnects for you.
8699
8711
  */
8700
8712
  streamEvents(opts?: {
8713
+ /** @deprecated Ignored: the stream keeps no position. */
8701
8714
  cursor?: number;
8702
8715
  signal?: AbortSignal;
8703
- }): AsyncGenerator<Action, void, void>;
8716
+ }): AsyncGenerator<RealtimeEvent, void, void>;
8704
8717
  /**
8705
- * The workspace's realtime events, polled from `GET /v1/events/poll`
8706
- * every two seconds (at once while the server has more), with retries
8707
- * until `close()`: the ledger and the caller's notifications as
8708
- * wake-ups, the workspace's frames as they are, and who is online when
8709
- * that changed. Each poll keeps the caller online. The web app polls the
8710
- * same route through its own server route.
8718
+ * The workspace's realtime events from `GET /v1/events/stream`, opened
8719
+ * again with backoff whenever it drops, until `close()`: the ledger and
8720
+ * the caller's notifications as wake-ups, the workspace's frames as they
8721
+ * are, and who is online. The connection keeps the caller online.
8711
8722
  */
8712
8723
  openRealtimeSocket(options: RealtimeSocketOptions): RealtimeSocket;
8724
+ /**
8725
+ * One chat thread's own stream (`GET /v1/threads/{id}/stream`), for a
8726
+ * member who sits in it: the answers its agent runs are writing
8727
+ * (`run_delta`) and each run step's end (`run`). It opens the stream
8728
+ * again with backoff whenever it drops or the server ends it, until
8729
+ * `signal` aborts; a refusal that will not change (401, 403, the thread
8730
+ * not found as 404) throws an `ApiError`.
8731
+ *
8732
+ * Every connection first replays the turn being written, so a reader
8733
+ * that reconnects mid-answer has all of it. Fold the pieces by
8734
+ * `(seq, n)`: a later `seq` starts the run's text over, a piece already
8735
+ * held (the same `seq`, an `n` at or below the last) changes nothing.
8736
+ * The answer itself always lands as a message; a `run` frame whose
8737
+ * outcome is `continue` or `parked` means the text so far was preamble.
8738
+ * A step that ended while the stream was down is not replayed, so
8739
+ * `onOpen` after the first is the moment to re-read the thread.
8740
+ */
8741
+ streamThread(threadId: string, opts?: {
8742
+ signal?: AbortSignal;
8743
+ /** Called each time the stream answers. */
8744
+ onOpen?: () => void;
8745
+ }): AsyncGenerator<ThreadStreamEvent, void, void>;
8713
8746
  /** Say the caller is writing in a thread or an inbox conversation (`POST /v1/events/typing`); nothing is stored. */
8714
8747
  sendTyping(input: {
8715
8748
  scope: TypingScope;