@langchain/langgraph-sdk/dist/client/stream/media.d.cts

Client library for interacting with the LangGraph API

import { MessagesEvent } from "@langchain/protocol";

//#region src/client/stream/media.d.ts
/**
 * Block types this assembler knows how to reassemble into media handles.
 */
type MediaBlockType = "audio" | "image" | "video" | "file";
/**
 * Kinds of failure that can terminate a media handle prematurely.
 *
 * - `"message-error"` — the upstream message emitted an `error` event
 *   before completion.
 * - `"stream-closed"` — the transport stream closed before
 *   `message-finish` arrived (thread closed, transport dropped, etc.).
 * - `"fetch-failed"` — the block was `url`-sourced and the lazy
 *   `fetch()` rejected (CORS, 404, 5xx, network).
 */
type MediaAssemblyErrorKind = "message-error" | "stream-closed" | "fetch-failed";
/**
 * Typed error thrown through `media.stream` / rejected from
 * `media.blob` / `media.objectURL` when a handle fails before its
 * message completes. Carries the bytes accumulated up to the failure
 * point on `partialBytes` for callers that want to salvage or diagnose.
 */
declare class MediaAssemblyError extends Error {
  readonly kind: MediaAssemblyErrorKind;
  readonly messageId: string;
  readonly partialBytes: Uint8Array;
  readonly cause?: unknown;
  constructor(kind: MediaAssemblyErrorKind, messageId: string, partialBytes: Uint8Array, message?: string, options?: {
    cause?: unknown;
  });
}
/**
 * Shared surface across every media handle returned by
 * {@link MediaAssembler}.
 *
 * The handle is live while its parent message is active:
 *  - `partialBytes` is a snapshot of all bytes received so far.
 *  - `stream` is a lazy, single-consumer byte stream (see
 *    accessor docstring).
 *  - `blob` / `objectURL` settle on `message-finish`.
 *  - `error` becomes set if the handle terminates in any of the
 *    {@link MediaAssemblyErrorKind} failure modes.
 */
interface MediaBase {
  readonly messageId: string;
  readonly namespace: string[];
  readonly node?: string;
  /** `id` from the originating content block, if the provider sent one. */
  readonly id?: string;
  readonly mimeType?: string;
  /**
   * Present iff the originating block carried `url` (not `data`).
   * When set, `blob` / `stream` / `objectURL` lazily fetch from here
   * on first access.
   */
  readonly url?: string;
  /**
   * Live byte stream.
   *
   * Lazy: not materialised unless accessed. On first access the
   * stream is seeded with every byte already accumulated
   * (`partialBytes`) and then wired to future chunks. For URL-sourced
   * blocks, first access triggers `fetch()` and pipes the response
   * body through.
   *
   * Repeated access returns the same {@link ReadableStream} reference
   * — you can safely read it once, release the lock, and re-acquire a
   * reader later (e.g. React StrictMode effect re-invokes). The
   * standard `ReadableStream.locked` semantics prevent concurrent
   * readers; use `stream.tee()` when you truly need multiple live
   * consumers.
   */
  readonly stream: ReadableStream<Uint8Array>;
  /** Resolves on `message-finish` with the concatenated {@link Blob}. */
  readonly blob: Promise<Blob>;
  /**
   * Lazy {@link URL.createObjectURL} over {@link blob}. Cached: first
   * access creates the URL, subsequent accesses return the same one.
   * Call {@link revoke} to free the URL slot; the next access creates
   * a fresh URL. `ThreadStream.close()` auto-revokes as a safety net.
   */
  readonly objectURL: Promise<string>;
  /** Live view of accumulated bytes. Settles with final bytes on finish. */
  readonly partialBytes: Uint8Array;
  /** Set iff the handle settled in an error state. */
  readonly error?: MediaAssemblyError;
  /** Diagnostic: `false` if block indices arrived out of order. */
  readonly monotonic: boolean;
  /**
   * Revoke the currently-cached object URL (if any). Subsequent
   * accesses to {@link objectURL} create a fresh URL from the Blob.
   * Idempotent.
   */
  revoke(): void;
}
interface AudioMedia extends MediaBase {
  readonly type: "audio";
  /**
   * Concatenated transcript across every audio block in this message.
   * Resolves on `message-finish` with the joined string, or `undefined`
   * when no block carried a transcript.
   */
  readonly transcript: Promise<string | undefined>;
}
interface ImageMedia extends MediaBase {
  readonly type: "image";
  /** Pixel width, if the provider sent it on the originating block. */
  readonly width?: number;
  /** Pixel height, if the provider sent it on the originating block. */
  readonly height?: number;
}
interface VideoMedia extends MediaBase {
  readonly type: "video";
}
interface FileMedia extends MediaBase {
  readonly type: "file";
  /** File name hint, if the provider sent it on the originating block. */
  readonly filename?: string;
}
type AnyMediaHandle = AudioMedia | ImageMedia | VideoMedia | FileMedia;
/**
 * Dispatch callbacks receive a freshly-started handle on its first
 * matching `content-block-start`. Exactly one callback fires per
 * `(messageId, blockType)` pair.
 */
interface MediaAssemblerCallbacks {
  onAudio?: (media: AudioMedia) => void;
  onImage?: (media: ImageMedia) => void;
  onVideo?: (media: VideoMedia) => void;
  onFile?: (media: FileMedia) => void;
  /**
   * Invoked for every type; receives the same handle as the typed
   * callback. Useful for writing one "all media" consumer without
   * registering four type-specific callbacks.
   */
  onMedia?: (media: AnyMediaHandle) => void;
}
interface MediaAssemblerOptions extends MediaAssemblerCallbacks {
  /**
   * Injected `fetch` used for URL-sourced blocks. Defaults to the
   * global `fetch`. Throws on first URL access if neither is present.
   */
  fetch?: typeof fetch;
}
declare class MediaAssembler {
  #private;
  constructor(options?: MediaAssemblerOptions);
  /**
   * Fold a single `messages` event. Non-media blocks and
   * informational events (e.g. `content-block-finish`) are no-ops.
   */
  consume(event: MessagesEvent): void;
  /**
   * Abort all outstanding handles with a `stream-closed` error.
   * Called when the upstream event source terminates before the
   * messages it was assembling had a chance to finish.
   */
  close(): void;
}
//#endregion
export { AnyMediaHandle, AudioMedia, FileMedia, ImageMedia, MediaAssembler, MediaAssemblerCallbacks, MediaAssemblerOptions, MediaAssemblyError, MediaAssemblyErrorKind, MediaBase, MediaBlockType, VideoMedia };
//# sourceMappingURL=media.d.cts.map