@opengeni/sdk 4.4.1 → 4.5.0

package/dist/site.js

@@ -24,13 +24,13 @@ import {
   sanitizeOpenGeniSiteToolInvokeRequest,
   serveSiteHttp,
   siteSessionPath
-} from "./chunk-ALXDFL6C.js";
+} from "./chunk-VSOXNL3T.js";
 import "./chunk-OV3POE62.js";
 import "./chunk-ORYDCRFM.js";
-import "./chunk-PVWOBYAZ.js";
+import "./chunk-BXMNDWAN.js";
 import "./chunk-X5ITQVXE.js";
 import "./chunk-72YZCZWF.js";
-import "./chunk-BLID3DCD.js";
+import "./chunk-V4AIZAFF.js";
 import "./chunk-POYRW6KT.js";
 import "./chunk-ODKRQUWR.js";
 export {

package/dist/types.d.ts

@@ -1649,6 +1649,32 @@ export type SessionListTotals = {
         waiting?: number;
     }>;
 };
+/**
+ * One Site row in one project (`siteConversations: "group"`): a Site with
+ * the viewer's conversations, created by a chat they list, or opened by them.
+ * Counts are complete for the viewer, independent of page size.
+ */
+export type SiteConversationGroup = {
+    siteId: string;
+    channelId: string | null;
+    /** The Site's current title when the viewer can read it, else its creation label. */
+    title: string;
+    /** Root conversations in the group; 0 for a Site with none yet. */
+    conversations: number;
+    /** Latest activity: its conversations, its own changes, or the viewer opening it. */
+    updatedAt: string;
+    /** Creation time of the group's newest conversation, else of the Site. */
+    createdAt: string;
+    total: number;
+    attention: number;
+    attentionSince: string | null;
+    failed: number;
+    active: number;
+    queued: number;
+    waiting: number;
+    unread: number;
+    activeWork: number;
+};
 export type SessionListResponse = {
     totals?: SessionListTotals;
     needsYouOnly?: true;
@@ -1669,6 +1695,12 @@ export type SessionListResponse = {
     originSiteId?: string;
     /** Server-resolved Site access filter, when requested. */
     siteAccessId?: string;
+    /** Receipt for the requested Site conversation mode. */
+    siteConversations?: "include" | "group";
+    /** Complete Site rows for a `group` root page, newest activity first. */
+    siteGroups?: SiteConversationGroup[];
+    /** True when Site rows beyond the server bound were omitted. */
+    siteGroupsTruncated?: true;
     sessions: Session[];
     nextCursor: string | null;
 };
@@ -4157,6 +4189,14 @@ export type ClientConfig = {
     claudeSubscriptionEnabled?: boolean | undefined;
     /** Whether people can connect their own computers; absent on older servers. */
     connectedMachines?: boolean | undefined;
+    /**
+     * The Chrome extension people add to connect their own Chrome, and its
+     * Chrome Web Store page; absent on older servers (Opengeni Browser).
+     */
+    browserExtension?: {
+        name: string;
+        installUrl: string;
+    } | undefined;
     defaultModel: string;
     allowedModels: string[];
     models: ClientModel[];

package/dist/workspace-artifacts.d.ts

@@ -26,6 +26,11 @@ export type WorkspaceArtifactVersion = {
     createdBySubjectId: string;
     createdAt: string;
 };
+/** This person's latest recorded open of a Site, which orders its sidebar row. */
+export type SiteOpenedResponse = {
+    /** When the open was recorded (ISO 8601). */
+    openedAt: string;
+};
 /** Who can see a Site: everyone in the workspace, or only its owner ("Only me"). */
 export type WorkspaceArtifactVisibility = "private" | "workspace";
 export type WorkspaceArtifact = {

package/dist/workspace-live-stream.d.ts

@@ -7,6 +7,13 @@ export type WorkspaceSessionListEvent = {
     workspaceId: string;
     available: boolean;
     sessionIds: string[] | null;
+    /**
+     * Changed Site conversations visible to this viewer. Ordinary lists omit
+     * them; only a surface that shows Site conversations needs these. A hint
+     * whose `sessionIds` is empty and that carries only these changes nothing
+     * for ordinary lists.
+     */
+    siteSessionIds?: string[];
 };
 export type WorkspaceLiveEvent = WorkspaceControlEvent | WorkspaceInteractionRevisionEvent | WorkspaceSessionListEvent;
 export type WorkspaceLiveStreamOptions = Omit<StreamSessionEventsOptions, "after"> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "description": "Framework-agnostic TypeScript SDK for the Opengeni API: typed client, session lifecycle, SSE event streaming with reconnect + replay-by-sequence, and proxy re-streaming helpers.",
   "license": "Apache-2.0",
   "repository": {
@@ -218,8 +218,8 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/connect": "4.4.1",
-    "@opengeni/contracts": "4.4.1"
+    "@opengeni/connect": "4.5.0",
+    "@opengeni/contracts": "4.5.0"
   },
   "engines": {
     "node": ">=18"

package/src/browser.ts

@@ -45,6 +45,8 @@ export {
   isRetryableStreamError,
 } from "./errors";
 export type { OpenGeniSecureContextRequiredReason } from "./errors";
+export { isTransientRequestError } from "./read-retry";
+export type { OpenGeniReadRetryOptions } from "./read-retry";
 export { resolveWorkspaceVoiceInputEnabled } from "./transcription";
 export { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./types";
 

package/src/client.ts

@@ -104,6 +104,7 @@ import type {
 } from "./knowledge";
 import type {
   DuplicateWorkspaceArtifactRequest,
+  SiteOpenedResponse,
   RollbackWorkspaceArtifactRequest,
   SetWorkspaceArtifactStatusRequest,
   UpdateWorkspaceArtifactVisibilityRequest,
@@ -150,6 +151,19 @@ import {
 } from "./stream";
 import type { SessionModelContextResponse } from "./model-context";
 import { withDeprecationNotices, type OpenGeniDeprecationHandler } from "./deprecation";
+import {
+  abortableReadRetryDelay,
+  isSafeReadMethod,
+  isTransientGatewayStatus,
+  invalidApiResponseError,
+  isTransientRequestError,
+  markTransportFailure,
+  parseRetryAfterMs,
+  readRetryDelayMs,
+  resolveReadRetryPolicy,
+  type OpenGeniReadRetryOptions,
+  type ReadRetryPolicy,
+} from "./read-retry";
 import type {
   SkillRecord,
   SkillSummary,
@@ -825,6 +839,13 @@ export type SessionListPageOptions = {
   mineOnly?: boolean;
   /** Created through this Site. In a Site-bound client, "current" resolves to its own Site. */
   originSiteId?: string;
+  /**
+   * Conversations that run inside a Site are left out of ordinary lists.
+   * `include` lists them as ordinary rows; `group` (a root page) keeps them
+   * out of the rows and returns one `siteGroups` entry per Site and project.
+   * Older servers omit the `siteConversations` receipt and the Site rows.
+   */
+  siteConversations?: "include" | "group";
   limit?: number;
   parentSessionId?: string | null;
   /** Only sessions carrying this exact opaque end-user label. */
@@ -915,6 +936,15 @@ export type WorkspaceControlEventPage = {
   nextAfter: number | null;
 };
 
+/** What one safe-read attempt observed, for the retry decision. */
+type ReadAttemptOutcome = {
+  /** `fetch` or the response body rejected (reset connection, HTTP/2 error, ...). */
+  transportFailure: boolean;
+  /** A real 502, 503 or 504 response. */
+  gatewayFailure: boolean;
+  retryAfterMs: number | null;
+};
+
 export type OpenGeniClientOptions = {
   /** Explicit compatibility for an API predating targeted tool calls. No automatic downgrade. */
   toolGatewayMode?: "target" | "catalog";
@@ -954,6 +984,14 @@ export type OpenGeniClientOptions = {
    * `"compatible"` everywhere else.
    */
   apiContract?: "strict" | "compatible" | undefined;
+  /**
+   * Bounded quiet retry for safe JSON reads (`GET`/`HEAD`) that fail
+   * transiently: a transport error or a 502, 503 or 504 (honoring
+   * `Retry-After`). This rides out API rolling deploys and short network
+   * blips. Mutations are never retried. On by default (4 attempts within
+   * 5 seconds); pass `false` to turn it off or options to tune it.
+   */
+  readRetry?: OpenGeniReadRetryOptions | false | undefined;
 };
 
 function defaultApiContractMode(options: OpenGeniClientOptions): "strict" | "compatible" {
@@ -1190,6 +1228,7 @@ export class OpenGeniClient {
   private readonly fetchImpl: FetchLike;
   private readonly sessionCommandTimeoutMs: number;
   private readonly apiContractStrict: boolean;
+  private readonly readRetryPolicy: ReadRetryPolicy | null;
   private readonly active = new Map<string, SingleFlightReadEntry>();
   private readonly generations = new Map<string, number>();
   private readonly queued = new Map<string, SingleFlightReadEntry>();
@@ -1212,6 +1251,7 @@ export class OpenGeniClient {
     }
     this.sessionCommandTimeoutMs = sessionCommandTimeoutMs;
     this.apiContractStrict = defaultApiContractMode(options) === "strict";
+    this.readRetryPolicy = resolveReadRetryPolicy(options.readRetry);
     this.interaction = new OpenGeniInteractionClient(this);
     this.tools = createLazyToolsFacade(this);
   }
@@ -1326,7 +1366,7 @@ export class OpenGeniClient {
       options.signal ? { signal: options.signal } : {},
     );
     if (!isTranscriptionRecordingListResponse(body)) {
-      throw new OpenGeniApiError(502, "Invalid transcription recording list response.", {
+      throw invalidApiResponseError("Invalid transcription recording list response.", {
         code: "invalid_response",
       });
     }
@@ -1998,6 +2038,7 @@ export class OpenGeniClient {
       if (options.mineOnly) query.mineOnly = "true";
       if (options.includePinned === false) query.includePinned = "false";
       if (options.archivedOnly) query.archivedOnly = "true";
+      if (options.siteConversations) query.siteConversations = options.siteConversations;
       result = await this.requestJson<SessionListResponse | SessionListEntryResponse | Session[]>(
         "GET",
         path,
@@ -2078,6 +2119,17 @@ export class OpenGeniClient {
     return response;
   }
 
+  /**
+   * Record that this person opened a Site, which orders its sidebar row like
+   * session activity. Personal; needs `artifacts:read`.
+   */
+  async recordSiteOpened(workspaceId: string, siteId: string): Promise<SiteOpenedResponse> {
+    return this.requestJson(
+      "POST",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/published-artifacts/${encodeURIComponent(siteId)}/opened`,
+    );
+  }
+
   /** Console/owner-authorized agent only. Never available through the Site frame bridge. */
   async listSiteSessionAccess(
     workspaceId: string,
@@ -4772,7 +4824,7 @@ export class OpenGeniClient {
       header.length > 64 * 1024
     ) {
       await cancelResponseBody(response, "browser frame metadata is invalid");
-      throw new OpenGeniApiError(502, "browser frame metadata is invalid");
+      throw invalidApiResponseError("browser frame metadata is invalid");
     }
     let metadata: BrowserFrameMetadata;
     try {
@@ -4781,7 +4833,7 @@ export class OpenGeniClient {
       );
     } catch {
       await cancelResponseBody(response, "browser frame metadata is invalid");
-      throw new OpenGeniApiError(502, "browser frame metadata is invalid");
+      throw invalidApiResponseError("browser frame metadata is invalid");
     }
     const data = await readBoundedResponseBytes(response, 24 * 1024 * 1024, null);
     if (
@@ -4789,7 +4841,7 @@ export class OpenGeniClient {
       metadata.targetId !== targetId ||
       metadata.mediaType !== mediaType
     ) {
-      throw new OpenGeniApiError(502, "browser frame evidence does not match its request");
+      throw invalidApiResponseError("browser frame evidence does not match its request");
     }
     return { ...metadata, data };
   }
@@ -4838,7 +4890,7 @@ export class OpenGeniClient {
       options,
     );
     if (state.browserSessionId !== browserSessionId || state.targetId !== targetId) {
-      throw new OpenGeniApiError(502, "browser target state belongs to another binding");
+      throw invalidApiResponseError("browser target state belongs to another binding");
     }
     return state;
   }
@@ -4865,7 +4917,7 @@ export class OpenGeniClient {
       result.documentGeneration !== request.expectedDocumentGeneration ||
       result.frameId !== request.expectedFrameId
     ) {
-      throw new OpenGeniApiError(502, "browser DOM read belongs to another binding");
+      throw invalidApiResponseError("browser DOM read belongs to another binding");
     }
     return result;
   }
@@ -5193,19 +5245,19 @@ export class OpenGeniClient {
     const mediaType = response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
     if (mediaType !== "image/jpeg" && mediaType !== "image/png") {
       await cancelResponseBody(response, "computer frame media type is invalid");
-      throw new OpenGeniApiError(502, "computer frame media type is invalid");
+      throw invalidApiResponseError("computer frame media type is invalid");
     }
     const metadataHeader = response.headers.get("x-opengeni-computer-frame");
     if (!metadataHeader || metadataHeader.length > 32 * 1024) {
       await cancelResponseBody(response, "computer frame metadata is invalid");
-      throw new OpenGeniApiError(502, "computer frame metadata is invalid");
+      throw invalidApiResponseError("computer frame metadata is invalid");
     }
     let metadata: ReturnType<typeof decodeComputerFrameMetadataHeader>;
     try {
       metadata = decodeComputerFrameMetadataHeader(metadataHeader);
     } catch {
       await cancelResponseBody(response, "computer frame metadata is invalid");
-      throw new OpenGeniApiError(502, "computer frame metadata is invalid");
+      throw invalidApiResponseError("computer frame metadata is invalid");
     }
     const bytes = await readBoundedResponseBytes(response, 256 * 1024, null);
     const mismatchReason = computerFrameEvidenceMismatchReason(metadata, {
@@ -5215,7 +5267,7 @@ export class OpenGeniClient {
       sha256: await sha256Hex(bytes),
     });
     if (mismatchReason) {
-      throw new OpenGeniApiError(502, "computer frame evidence does not match its request");
+      throw invalidApiResponseError("computer frame evidence does not match its request");
     }
     return { ...metadata, data: bytes };
   }
@@ -7801,7 +7853,7 @@ export class OpenGeniClient {
       metadata.originalBytes <= 0 ||
       metadata.originalBytes > COMPUTER_SCREENSHOT_MAX_BYTES
     ) {
-      throw new OpenGeniApiError(502, "retained screenshot metadata is invalid");
+      throw invalidApiResponseError("retained screenshot metadata is invalid");
     }
     const bytes = await this.downloadRetainedArtifactBytes(metadata, options);
     return { metadata, bytes };
@@ -7818,7 +7870,7 @@ export class OpenGeniClient {
     const bytes = new Uint8Array(artifact.originalBytes);
     const pageBytes = Math.min(artifact.retrieval.maxRangeBytes, RETAINED_OUTPUT_MAX_PAGE_BYTES);
     if (!Number.isSafeInteger(pageBytes) || pageBytes <= 0) {
-      throw new OpenGeniApiError(502, "retained artifact range metadata is invalid");
+      throw invalidApiResponseError("retained artifact range metadata is invalid");
     }
     for (let start = 0; start < bytes.byteLength; start += pageBytes) {
       options.signal?.throwIfAborted();
@@ -7841,7 +7893,7 @@ export class OpenGeniClient {
           }
         }
       }
-      if (!page) throw new OpenGeniApiError(502, "retained artifact range retry exhausted");
+      if (!page) throw invalidApiResponseError("retained artifact range retry exhausted");
       const expectedLength = end - start + 1;
       if (
         page.status !== 206 ||
@@ -7849,12 +7901,12 @@ export class OpenGeniClient {
         page.contentLength !== expectedLength ||
         page.contentRange !== `bytes ${start}-${end}/${artifact.originalBytes}`
       ) {
-        throw new OpenGeniApiError(502, "retained artifact range response is invalid");
+        throw invalidApiResponseError("retained artifact range response is invalid");
       }
       bytes.set(page.bytes, start);
     }
     if ((await sha256Hex(bytes)) !== artifact.sha256) {
-      throw new OpenGeniApiError(502, "retained artifact checksum mismatch");
+      throw invalidApiResponseError("retained artifact checksum mismatch");
     }
     return bytes;
   }
@@ -7894,7 +7946,7 @@ export class OpenGeniClient {
     }
     if (response.headers.get("accept-ranges") !== "bytes") {
       await cancelResponseBody(response, "retained artifact response omitted byte-range support");
-      throw new OpenGeniApiError(502, "retained artifact response omitted byte-range support");
+      throw invalidApiResponseError("retained artifact response omitted byte-range support");
     }
     let declaredLength: number | null;
     try {
@@ -11363,64 +11415,130 @@ export class OpenGeniClient {
     const correlationId = crypto.randomUUID();
     const abort = requestAbortSignal(options);
     try {
-      if (abort.signal?.aborted) {
-        throw abort.signal.reason ?? new DOMException("Request aborted", "AbortError");
-      }
-      const headers = this.headers(correlationId);
-      let response: FetchResponse;
-      try {
-        response = await awaitWithAbort(
-          this.fetchImpl(this.url(path, query), {
-            method,
-            headers: {
-              ...headers,
-              Accept: "application/json",
-              ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
-            },
-            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-            ...(abort.signal ? { signal: abort.signal } : {}),
-          }),
+      const retryPolicy = isSafeReadMethod(method) ? this.readRetryPolicy : null;
+      if (!retryPolicy) {
+        return await this.requestJsonAttempt<T>(
+          method,
+          path,
+          body,
+          query,
+          options,
           abort.signal,
+          correlationId,
+          null,
         );
-      } catch (error) {
-        if (options.signal?.aborted) throw error;
-        if (isMutationMethod(method)) {
-          throw mutationTransportError(correlationId);
-        }
-        throw error;
       }
-      assertApiContractResponse(response, this.apiContractStrict);
-      try {
-        if (!response.ok) {
-          throw await awaitWithAbort(
-            apiErrorFromResponse(response, { method, correlationId }),
+      // Safe reads only: a transient failure is retried quietly with jittered
+      // backoff (or the server's Retry-After) inside a small total budget.
+      const startedAt = Date.now();
+      for (let retry = 1; ; retry += 1) {
+        const attempt: ReadAttemptOutcome = {
+          transportFailure: false,
+          gatewayFailure: false,
+          retryAfterMs: null,
+        };
+        try {
+          return await this.requestJsonAttempt<T>(
+            method,
+            path,
+            body,
+            query,
+            options,
             abort.signal,
+            correlationId,
+            attempt,
           );
-        }
-        if (options.responseType === "void") {
-          await awaitWithAbort(
-            cancelResponseBody(response, "discarding void API response"),
-            abort.signal,
+        } catch (error) {
+          // Only the transport itself or a real 502/503/504 response is
+          // transient; a malformed success response is not retried.
+          const transient =
+            attempt.transportFailure || (attempt.gatewayFailure && isTransientRequestError(error));
+          if (abort.signal?.aborted || !transient) throw error;
+          const delay = readRetryDelayMs(
+            retryPolicy,
+            retry,
+            Date.now() - startedAt,
+            attempt.retryAfterMs,
           );
-          return undefined as T;
+          if (delay === null) throw error;
+          await abortableReadRetryDelay(delay, abort.signal);
         }
-        await awaitWithAbort(assertJsonResponse(response, { method, correlationId }), abort.signal);
-        const value = await awaitWithAbort(response.json(), abort.signal);
-        recordObservedSessionSequence(value, response.headers.get(SESSION_SEQUENCE_HEADER));
-        return value as T;
-      } catch (error) {
-        if (options.signal?.aborted) throw error;
-        if (error instanceof OpenGeniApiError) throw error;
-        if (isMutationMethod(method)) {
-          throw mutationTransportError(correlationId);
-        }
-        throw error;
       }
     } finally {
       abort.dispose();
     }
   }
 
+  private async requestJsonAttempt<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    query: Record<string, string>,
+    options: OpenGeniRequestOptions,
+    signal: AbortSignal | undefined,
+    correlationId: string,
+    attempt: ReadAttemptOutcome | null,
+  ): Promise<T> {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException("Request aborted", "AbortError");
+    }
+    const headers = this.headers(correlationId);
+    let response: FetchResponse;
+    try {
+      response = await awaitWithAbort(
+        this.fetchImpl(this.url(path, query), {
+          method,
+          headers: {
+            ...headers,
+            Accept: "application/json",
+            ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+          },
+          ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+          ...(signal ? { signal } : {}),
+        }),
+        signal,
+      );
+    } catch (error) {
+      if (options.signal?.aborted) throw error;
+      if (isMutationMethod(method)) {
+        throw mutationTransportError(correlationId);
+      }
+      if (error instanceof TypeError && attempt) attempt.transportFailure = true;
+      markTransportFailure(error);
+      throw error;
+    }
+    assertApiContractResponse(response, this.apiContractStrict);
+    try {
+      if (!response.ok) {
+        if (attempt && isTransientGatewayStatus(response.status)) {
+          attempt.gatewayFailure = true;
+          attempt.retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
+        }
+        throw await awaitWithAbort(
+          apiErrorFromResponse(response, { method, correlationId }),
+          signal,
+        );
+      }
+      if (options.responseType === "void") {
+        await awaitWithAbort(cancelResponseBody(response, "discarding void API response"), signal);
+        return undefined as T;
+      }
+      await awaitWithAbort(assertJsonResponse(response, { method, correlationId }), signal);
+      const value = await awaitWithAbort(response.json(), signal);
+      recordObservedSessionSequence(value, response.headers.get(SESSION_SEQUENCE_HEADER));
+      return value as T;
+    } catch (error) {
+      if (options.signal?.aborted) throw error;
+      if (error instanceof OpenGeniApiError) throw error;
+      if (isMutationMethod(method)) {
+        throw mutationTransportError(correlationId);
+      }
+      if (error instanceof TypeError && attempt) attempt.transportFailure = true;
+      markTransportFailure(error);
+      throw error;
+    }
+  }
+
   /** Authenticated, contract-checked response for bounded streaming downloads. */
   protected async requestResponse(
     method: string,
@@ -11565,7 +11683,7 @@ function isTranscriptionRecordingResponse(value: unknown): value is Transcriptio
 
 function transcriptionRecordingResponse(value: unknown): TranscriptionRecordingResponse {
   if (isTranscriptionRecordingResponse(value)) return value;
-  throw new OpenGeniApiError(502, "Invalid transcription recording response.", {
+  throw invalidApiResponseError("Invalid transcription recording response.", {
     code: "invalid_response",
   });
 }
@@ -11705,7 +11823,7 @@ async function assertJsonResponse(
 ): Promise<void> {
   if (isJsonContentType(response.headers.get("content-type"))) return;
   await cancelResponseBody(response, "unexpected non-JSON API response");
-  throw new OpenGeniApiError(502, "", {
+  throw invalidApiResponseError("", {
     code: "upstream_unavailable",
     retryable: true,
     correlationId: response.headers.get(OPENGENI_CORRELATION_HEADER) ?? context.correlationId,
@@ -11826,7 +11944,7 @@ function assertRetainedWorkspaceArtifactReceipt(
     !parseRetainedGeneratedImageReference(artifact, workspaceId) &&
     !parseRetainedWorkspaceFileReference(artifact, workspaceId)
   ) {
-    throw new OpenGeniApiError(502, "retained workspace artifact receipt is invalid");
+    throw invalidApiResponseError("retained workspace artifact receipt is invalid");
   }
 }
 
@@ -11837,16 +11955,16 @@ function assertSafeArtifactDownloadUrl(value: FileDownloadUrlResponse): void {
     typeof value.expiresAt !== "string" ||
     !Number.isFinite(Date.parse(value.expiresAt))
   ) {
-    throw new OpenGeniApiError(502, "retained artifact download URL is invalid");
+    throw invalidApiResponseError("retained artifact download URL is invalid");
   }
   let parsed: URL;
   try {
     parsed = new URL(value.url);
   } catch {
-    throw new OpenGeniApiError(502, "retained artifact download URL is invalid");
+    throw invalidApiResponseError("retained artifact download URL is invalid");
   }
   if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password) {
-    throw new OpenGeniApiError(502, "retained artifact download URL is unsafe");
+    throw invalidApiResponseError("retained artifact download URL is unsafe");
   }
 }
 
@@ -11865,7 +11983,7 @@ function assertSafeVideoArtifactPlaybackSource(
     value.sizeBytes > GENERATED_VIDEO_MAX_BYTES ||
     !/^[0-9a-f]{64}$/.test(value.sha256)
   ) {
-    throw new OpenGeniApiError(502, "generated-video playback source is invalid");
+    throw invalidApiResponseError("generated-video playback source is invalid");
   }
   assertSafeArtifactDownloadUrl({ url: value.url, expiresAt: value.expiresAt });
 }
@@ -11873,11 +11991,11 @@ function assertSafeVideoArtifactPlaybackSource(
 function parseBoundedContentLength(value: string | null): number | null {
   if (value === null) return null;
   if (!/^\d+$/.test(value)) {
-    throw new OpenGeniApiError(502, "invalid retained artifact content-length");
+    throw invalidApiResponseError("invalid retained artifact content-length");
   }
   const length = Number(value);
   if (!Number.isSafeInteger(length) || length > RETAINED_OUTPUT_MAX_PAGE_BYTES) {
-    throw new OpenGeniApiError(502, "retained artifact response exceeds the SDK byte limit");
+    throw invalidApiResponseError("retained artifact response exceeds the SDK byte limit");
   }
   return length;
 }
@@ -11889,7 +12007,7 @@ async function readBoundedResponseBytes(
 ): Promise<Uint8Array> {
   if (!response.body) {
     if (expectedBytes !== null && expectedBytes !== 0) {
-      throw new OpenGeniApiError(502, "retained artifact response length mismatch");
+      throw invalidApiResponseError("retained artifact response length mismatch");
     }
     return new Uint8Array();
   }
@@ -11905,7 +12023,7 @@ async function readBoundedResponseBytes(
         await reader
           .cancel("retained artifact response exceeded the SDK byte limit")
           .catch(() => undefined);
-        throw new OpenGeniApiError(502, "retained artifact response exceeds the SDK byte limit");
+        throw invalidApiResponseError("retained artifact response exceeds the SDK byte limit");
       }
       chunks.push(value);
     }
@@ -11913,7 +12031,7 @@ async function readBoundedResponseBytes(
     reader.releaseLock();
   }
   if (expectedBytes !== null && totalBytes !== expectedBytes) {
-    throw new OpenGeniApiError(502, "retained artifact response length mismatch");
+    throw invalidApiResponseError("retained artifact response length mismatch");
   }
   const bytes = new Uint8Array(totalBytes);
   let offset = 0;

package/src/core.ts

@@ -35,6 +35,8 @@ export {
   isRetryableStreamError,
 } from "./errors";
 export type { OpenGeniSecureContextRequiredReason } from "./errors";
+export { isTransientRequestError } from "./read-retry";
+export type { OpenGeniReadRetryOptions } from "./read-retry";
 export { parseDeprecationNotice } from "./deprecation";
 export type { OpenGeniDeprecationHandler, OpenGeniDeprecationNotice } from "./deprecation";
 export { resolveWorkspaceVoiceInputEnabled } from "./transcription";