@opengeni/sdk 0.23.0 → 0.25.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/sdk",
-  "version": "0.23.0",
+  "version": "0.25.5",
   "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": {

package/src/client.ts

@@ -1,4 +1,8 @@
-import { OpenGeniApiContractMismatchError, OpenGeniApiError } from "./errors";
+import {
+  OpenGeniApiContractMismatchError,
+  OpenGeniApiError,
+  OpenGeniSessionListCursorError,
+} from "./errors";
 import {
   streamSessionEvents,
   type SessionEventStreamTransport,
@@ -29,6 +33,8 @@ import type {
   CapabilityCatalogResponse,
   CapabilityInstallation,
   AddDocumentRequest,
+  CreateKnowledgeDropRequest,
+  MoveDocumentRequest,
   ClientConfig,
   WorkspaceModelCatalogResponse,
   ClientSessionEventInput,
@@ -112,7 +118,9 @@ import type {
   DeleteSessionQueueItemRequest,
   EditSessionQueueItemRequest,
   MoveSessionQueueItemRequest,
+  NewSessionDraft,
   SaveComposerDraftRequest,
+  SaveNewSessionDraftRequest,
   SteerSessionQueueItemRequest,
   SessionControlResponse,
   WorkspaceInferenceControlResponse,
@@ -164,6 +172,7 @@ import type {
   UpdateScheduledTaskRequest,
   UpdateSessionGoalRequest,
   UpdateSessionRequest,
+  UpdateSessionToolPolicyRequest,
   UpdateVariableSetRequest,
   UpdateRigRequest,
   UpdateWorkspaceMemberRequest,
@@ -190,9 +199,21 @@ import type {
 import {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
+  OPENGENI_CORRELATION_HEADER,
   RETAINED_OUTPUT_MAX_PAGE_BYTES,
 } from "./types";
 
+function sessionListQuery(options: {
+  limit?: number;
+  parentSessionId?: string | null;
+}): Record<string, string> {
+  const { limit, parentSessionId } = options;
+  return {
+    ...(limit === undefined ? {} : { limit: String(limit) }),
+    ...(parentSessionId === undefined ? {} : { parentSessionId: parentSessionId ?? "null" }),
+  };
+}
+
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 
 export type WorkspaceControlEventPage = {
@@ -269,6 +290,24 @@ export class OpenGeniClient {
     );
   }
 
+  async getNewSessionDraft(workspaceId: string): Promise<NewSessionDraft> {
+    return await this.requestJson<NewSessionDraft>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/new-session-draft`,
+    );
+  }
+
+  async saveNewSessionDraft(
+    workspaceId: string,
+    request: SaveNewSessionDraftRequest,
+  ): Promise<NewSessionDraft> {
+    return await this.requestJson<NewSessionDraft>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/new-session-draft`,
+      request,
+    );
+  }
+
   async getSession(workspaceId: string, sessionId: string): Promise<Session> {
     return await this.requestJson<Session>(
       "GET",
@@ -288,6 +327,19 @@ export class OpenGeniClient {
     );
   }
 
+  /** Replace the durable tool policy or explicitly adopt workspace defaults. */
+  async updateSessionToolPolicy(
+    workspaceId: string,
+    sessionId: string,
+    request: UpdateSessionToolPolicyRequest,
+  ): Promise<Session> {
+    return await this.requestJson<Session>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/tool-policy`,
+      request,
+    );
+  }
+
   /**
    * Replace one attached MCP server's approval policy. The change is captured
    * by the next claimed attempt; already-claimed work keeps its immutable
@@ -314,21 +366,21 @@ export class OpenGeniClient {
       search?: string;
     } = {},
   ): Promise<Session[]> {
+    // Search was added with the pin-aware page endpoint. An older API silently
+    // ignores unknown query parameters on the historical array endpoint, which
+    // would turn a search into a plausible-looking unfiltered result. Route
+    // searches through listSessionPage so its rolling-version shape check can
+    // fail explicitly on an older server; retain the array endpoint for every
+    // pre-existing call shape.
+    if (options.search?.trim()) {
+      const page = await this.listSessionPage(workspaceId, options);
+      return [...page.pinned, ...page.sessions];
+    }
     return await this.requestJson<Session[]>(
       "GET",
       `/v1/workspaces/${workspaceId}/sessions`,
       undefined,
-      {
-        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
-        ...(options.search?.trim() ? { search: options.search.trim() } : {}),
-        ...(Object.prototype.hasOwnProperty.call(options, "parentSessionId") &&
-        options.parentSessionId !== undefined
-          ? {
-              parentSessionId:
-                options.parentSessionId === null ? "null" : String(options.parentSessionId),
-            }
-          : {}),
-      },
+      sessionListQuery(options),
     );
   }
 
@@ -340,26 +392,57 @@ export class OpenGeniClient {
       parentSessionId?: string | null;
       cursor?: string;
       search?: string;
+      /** Return only the complete personal pinned projection. */
+      pinsOnly?: boolean;
     } = {},
   ): Promise<SessionListResponse> {
-    return await this.requestJson<SessionListResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/sessions`,
-      undefined,
-      {
-        view: "page",
-        ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
-        ...(options.cursor !== undefined ? { cursor: options.cursor } : {}),
-        ...(options.search?.trim() ? { search: options.search.trim() } : {}),
-        ...(Object.prototype.hasOwnProperty.call(options, "parentSessionId") &&
-        options.parentSessionId !== undefined
-          ? {
-              parentSessionId:
-                options.parentSessionId === null ? "null" : String(options.parentSessionId),
-            }
-          : {}),
-      },
-    );
+    const search = options.search?.trim();
+    let response: SessionListResponse | Session[];
+    try {
+      response = await this.requestJson<SessionListResponse | Session[]>(
+        "GET",
+        `/v1/workspaces/${workspaceId}/sessions`,
+        undefined,
+        {
+          view: "page",
+          ...sessionListQuery(options),
+          ...(options.cursor !== undefined ? { cursor: options.cursor } : {}),
+          ...(search ? { search } : {}),
+          ...(options.pinsOnly ? { pinsOnly: "true" } : {}),
+        },
+      );
+    } catch (error) {
+      if (error instanceof OpenGeniApiError && error.status === 410) {
+        throw new OpenGeniSessionListCursorError(error.status, error.body, {
+          ...(error.code ? { code: error.code } : {}),
+          retryable: error.retryable,
+          ...(error.correlationId ? { correlationId: error.correlationId } : {}),
+          outcomeUnknown: error.outcomeUnknown,
+          displayMessage: "The session list changed — refresh and try again.",
+        });
+      }
+      throw error;
+    }
+    if (Array.isArray(response)) {
+      // Rolling/same-major compatibility: an older API ignores `view=page` and
+      // returns the historical array. That is an honest one-page projection;
+      // never pretend it honored a cursor supplied directly by a caller.
+      if (options.cursor) {
+        throw new Error("The connected OpenGeni API does not support stable session-page cursors");
+      }
+      // Older APIs ignore unknown query parameters. Treating their unfiltered
+      // array as a successful search would be worse than an explicit rolling-
+      // upgrade error (and client-side filtering cannot recover matches beyond
+      // the old endpoint's bounded first page).
+      if (search) {
+        throw new Error("The connected OpenGeni API does not support session search");
+      }
+      if (options.pinsOnly) {
+        throw new Error("The connected OpenGeni API does not support pins-only session lists");
+      }
+      return { pinned: [], sessions: response, nextCursor: null };
+    }
+    return response;
   }
 
   /** Set this authenticated member's personal workspace pin for a session. */
@@ -590,6 +673,7 @@ export class OpenGeniClient {
     }
     const listOptions: SessionEventListOptions | null =
       options.resultMode === "compact" ? null : options;
+    const correlationId = crypto.randomUUID();
     const response = await this.fetchImpl(
       this.url(`/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`, {
         ...(listOptions?.after !== undefined ? { after: String(listOptions.after) } : {}),
@@ -616,11 +700,14 @@ export class OpenGeniClient {
       }),
       {
         method: "GET",
-        headers: { ...this.headers(), Accept: "application/json" },
+        headers: { ...this.headers(correlationId), Accept: "application/json" },
       },
     );
     assertApiContractResponse(response);
-    if (!response.ok) throw new OpenGeniApiError(response.status, await safeText(response));
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, { method: "GET", correlationId });
+    }
+    await assertJsonResponse(response, { method: "GET", correlationId });
     const body = await response.json();
     if (options.resultMode === "compact") {
       return body as SessionEventCompactResult;
@@ -820,14 +907,15 @@ export class OpenGeniClient {
     const url = this.url(`/v1/workspaces/${workspaceId}/sessions/${sessionId}/events/stream`, {
       after: String(options.after ?? 0),
     });
+    const correlationId = crypto.randomUUID();
     const response = await this.fetchImpl(url, {
       method: "GET",
-      headers: { ...this.headers(), Accept: "text/event-stream" },
+      headers: { ...this.headers(correlationId), Accept: "text/event-stream" },
       ...(options.signal ? { signal: options.signal } : {}),
     });
     assertApiContractResponse(response);
     if (!response.ok) {
-      throw new OpenGeniApiError(response.status, await safeText(response));
+      throw await apiErrorFromResponse(response, { method: "GET", correlationId });
     }
     if (!response.body) {
       throw new OpenGeniApiError(response.status, "SSE response did not include a readable body");
@@ -973,6 +1061,7 @@ export class OpenGeniClient {
     workspaceId: string,
     options: { after?: number; limit?: number } = {},
   ): Promise<WorkspaceControlEventPage> {
+    const correlationId = crypto.randomUUID();
     const response = await this.fetchImpl(
       this.url(`/v1/workspaces/${workspaceId}/control-events`, {
         ...(options.after !== undefined ? { after: String(options.after) } : {}),
@@ -980,13 +1069,14 @@ export class OpenGeniClient {
       }),
       {
         method: "GET",
-        headers: { ...this.headers(), Accept: "application/json" },
+        headers: { ...this.headers(correlationId), Accept: "application/json" },
       },
     );
     assertApiContractResponse(response);
     if (!response.ok) {
-      throw new OpenGeniApiError(response.status, await safeText(response));
+      throw await apiErrorFromResponse(response, { method: "GET", correlationId });
     }
+    await assertJsonResponse(response, { method: "GET", correlationId });
     const events = (await response.json()) as WorkspaceControlEvent[];
     const bytesHeader = response.headers.get("X-OpenGeni-Page-Bytes");
     const nextHeader = response.headers.get("X-OpenGeni-Next-After");
@@ -1027,18 +1117,21 @@ export class OpenGeniClient {
     workspaceId: string,
     options: { after?: number; signal?: AbortSignal } = {},
   ): Promise<ReadableStream<Uint8Array>> {
+    const correlationId = crypto.randomUUID();
     const response = await this.fetchImpl(
       this.url(`/v1/workspaces/${workspaceId}/control-events/stream`, {
         after: String(options.after ?? 0),
       }),
       {
         method: "GET",
-        headers: { ...this.headers(), Accept: "text/event-stream" },
+        headers: { ...this.headers(correlationId), Accept: "text/event-stream" },
         ...(options.signal ? { signal: options.signal } : {}),
       },
     );
     assertApiContractResponse(response);
-    if (!response.ok) throw new OpenGeniApiError(response.status, await safeText(response));
+    if (!response.ok) {
+      throw await apiErrorFromResponse(response, { method: "GET", correlationId });
+    }
     if (!response.body) {
       throw new OpenGeniApiError(response.status, "SSE response did not include a readable body");
     }
@@ -1919,21 +2012,27 @@ export class OpenGeniClient {
    * -> complete. Returns the ready `FileAsset`.
    */
   async uploadFile(workspaceId: string, input: UploadFileInput): Promise<FileAsset> {
-    // Copy Uint8Array views into a Blob so byte offsets/shared buffers can't
-    // leak surrounding bytes into the PUT body.
+    // Snapshot mutable inputs before hashing so the digest always describes the
+    // exact bytes later sent to object storage. Copy Uint8Array views into a
+    // Blob so byte offsets/shared buffers can't leak surrounding bytes.
     const body: Blob | ArrayBuffer | string =
-      input.data instanceof Uint8Array ? new Blob([input.data.slice()]) : input.data;
+      input.data instanceof Uint8Array
+        ? new Blob([input.data.slice()])
+        : input.data instanceof ArrayBuffer
+          ? input.data.slice(0)
+          : input.data;
     const sizeBytes =
       typeof body === "string"
         ? new TextEncoder().encode(body).byteLength
         : body instanceof Blob
           ? body.size
           : body.byteLength;
+    const sha256 = input.sha256 ?? (await sha256ForUpload(body));
     const upload = await this.beginFileUpload(workspaceId, {
       filename: input.filename,
       contentType: input.contentType,
       sizeBytes,
-      ...(input.sha256 !== undefined ? { sha256: input.sha256 } : {}),
+      sha256,
     });
     const putResponse = await this.fetchImpl(upload.putUrl, {
       method: "PUT",
@@ -1947,7 +2046,7 @@ export class OpenGeniClient {
       body,
     });
     if (!putResponse.ok) {
-      throw new OpenGeniApiError(putResponse.status, await safeText(putResponse));
+      throw await apiErrorFromResponse(putResponse, { method: "PUT" });
     }
     return await this.completeFileUpload(workspaceId, upload.uploadId);
   }
@@ -1982,12 +2081,13 @@ export class OpenGeniClient {
     if (options.range && (options.range.length > 128 || /[^\x20-\x7e]/.test(options.range))) {
       throw new RangeError("retained artifact range must be at most 128 printable ASCII bytes");
     }
+    const correlationId = crypto.randomUUID();
     const response = await this.fetchImpl(
       this.url(`/v1/workspaces/${workspaceId}/artifacts/${artifactId}/content`),
       {
         method: "GET",
         headers: {
-          ...this.headers(),
+          ...this.headers(correlationId),
           Accept: "application/octet-stream",
           ...(options.range ? { Range: options.range } : {}),
         },
@@ -2001,7 +2101,7 @@ export class OpenGeniClient {
       throw error;
     }
     if (!response.ok) {
-      throw new OpenGeniApiError(response.status, await safeBoundedText(response));
+      throw await apiErrorFromResponse(response, { method: "GET", correlationId });
     }
     if (response.status !== 200 && response.status !== 206) {
       await cancelResponseBody(response, "unexpected retained artifact response status");
@@ -2091,6 +2191,39 @@ export class OpenGeniClient {
     );
   }
 
+  /**
+   * Drop raw text or an already-uploaded file into the workspace's Default
+   * base. When curation is enabled, it may name, summarize, categorize, and
+   * (confidence permitting) file the document into the best-matching base;
+   * provider=none leaves caller metadata and Default placement unchanged.
+   */
+  async createKnowledgeDrop(
+    workspaceId: string,
+    request: CreateKnowledgeDropRequest,
+  ): Promise<Document> {
+    return await this.requestJson<Document>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/knowledge/drops`,
+      request,
+    );
+  }
+
+  /**
+   * Move a document (and its indexed chunks) to another base. With no
+   * targetBaseId, applies the document's stored curation suggestion.
+   */
+  async moveDocument(
+    workspaceId: string,
+    documentId: string,
+    request: MoveDocumentRequest = {},
+  ): Promise<Document> {
+    return await this.requestJson<Document>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/documents/${documentId}/move`,
+      request,
+    );
+  }
+
   /** Retry indexing for a failed document. */
   async reindexDocument(
     workspaceId: string,
@@ -2393,15 +2526,12 @@ export class OpenGeniClient {
 
   // --- GitHub ----------------------------------------------------------------------------------
 
-  /** GitHub App configuration status; install/link URLs are null while new binding is disabled. */
+  /** GitHub App server configuration plus truthful workspace binding status. */
   async getGitHubApp(workspaceId: string): Promise<GitHubAppInfo> {
     return await this.requestJson<GitHubAppInfo>("GET", `/v1/workspaces/${workspaceId}/github/app`);
   }
 
-  /**
-   * Compatibility URL for previously issued state. New installation binding is
-   * disabled, so the endpoint validates state and terminates with HTTP 410.
-   */
+  /** Build the GitHub owner-consent entry URL for fresh workspace-bound state. */
   githubConnectUrl(workspaceId: string, state: string): string {
     return this.url(`/v1/workspaces/${workspaceId}/github/connect`, { state });
   }
@@ -2508,13 +2638,14 @@ export class OpenGeniClient {
 
   // --- Internals -------------------------------------------------------------
 
-  private headers(): Record<string, string> {
+  private headers(correlationId?: string): Record<string, string> {
     const extra =
       typeof this.options.headers === "function" ? this.options.headers() : this.options.headers;
     return {
       ...(this.options.apiKey ? { Authorization: `Bearer ${this.options.apiKey}` } : {}),
       ...extra,
       [OPENGENI_API_CONTRACT_HEADER]: OPENGENI_API_CONTRACT_REVISION,
+      ...(correlationId ? { [OPENGENI_CORRELATION_HEADER]: correlationId } : {}),
     };
   }
 
@@ -2678,37 +2809,63 @@ export class OpenGeniClient {
     query: Record<string, string> = {},
     options: OpenGeniRequestOptions = {},
   ): Promise<T> {
-    const response = await this.fetchImpl(this.url(path, query), {
-      method,
-      headers: {
-        ...this.headers(),
-        Accept: "application/json",
-        ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
-      },
-      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-      ...(options.signal ? { signal: options.signal } : {}),
-    });
+    const correlationId = crypto.randomUUID();
+    let response: Response;
+    try {
+      response = await this.fetchImpl(this.url(path, query), {
+        method,
+        headers: {
+          ...this.headers(correlationId),
+          Accept: "application/json",
+          ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+        },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+      });
+    } catch (error) {
+      if (isMutationMethod(method)) {
+        throw mutationTransportError(correlationId);
+      }
+      throw error;
+    }
     assertApiContractResponse(response);
     if (!response.ok) {
-      throw new OpenGeniApiError(response.status, await safeText(response));
+      throw await apiErrorFromResponse(response, { method, correlationId });
+    }
+    await assertJsonResponse(response, { method, correlationId });
+    try {
+      return (await response.json()) as T;
+    } catch (error) {
+      if (isMutationMethod(method)) {
+        throw mutationTransportError(correlationId);
+      }
+      throw error;
     }
-    return (await response.json()) as T;
   }
 
   /** Like `requestJson` for endpoints that respond with no body (204). */
   private async requestVoid(method: string, path: string, body?: unknown): Promise<void> {
-    const response = await this.fetchImpl(this.url(path), {
-      method,
-      headers: {
-        ...this.headers(),
-        Accept: "application/json",
-        ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
-      },
-      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-    });
+    const correlationId = crypto.randomUUID();
+    let response: Response;
+    try {
+      response = await this.fetchImpl(this.url(path), {
+        method,
+        headers: {
+          ...this.headers(correlationId),
+          Accept: "application/json",
+          ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+        },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      });
+    } catch (error) {
+      if (isMutationMethod(method)) {
+        throw mutationTransportError(correlationId);
+      }
+      throw error;
+    }
     assertApiContractResponse(response);
     if (!response.ok) {
-      throw new OpenGeniApiError(response.status, await safeText(response));
+      throw await apiErrorFromResponse(response, { method, correlationId });
     }
   }
 }
@@ -2720,22 +2877,86 @@ function assertApiContractResponse(response: Response): void {
   }
 }
 
-async function safeText(response: Response): Promise<string> {
-  try {
-    return await response.text();
-  } catch {
-    return "";
-  }
+const API_ERROR_MAX_BYTES = 16 * 1024;
+
+type ApiErrorRequestContext = {
+  method: string;
+  correlationId?: string | undefined;
+};
+
+async function apiErrorFromResponse(
+  response: Response,
+  context: ApiErrorRequestContext,
+): Promise<OpenGeniApiError> {
+  return new OpenGeniApiError(response.status, await readBoundedJsonErrorBody(response), {
+    correlationId: response.headers.get(OPENGENI_CORRELATION_HEADER) ?? context.correlationId,
+    mutation: isMutationMethod(context.method),
+  });
+}
+
+async function assertJsonResponse(
+  response: Response,
+  context: ApiErrorRequestContext,
+): Promise<void> {
+  if (isJsonContentType(response.headers.get("content-type"))) return;
+  await cancelResponseBody(response, "unexpected non-JSON API response");
+  throw new OpenGeniApiError(502, "", {
+    code: "upstream_unavailable",
+    retryable: true,
+    correlationId: response.headers.get(OPENGENI_CORRELATION_HEADER) ?? context.correlationId,
+    outcomeUnknown: isMutationMethod(context.method),
+    displayMessage: "OpenGeni is temporarily unavailable — retry.",
+  });
 }
 
-async function safeBoundedText(response: Response): Promise<string> {
+async function readBoundedJsonErrorBody(response: Response): Promise<string> {
+  if (!isJsonContentType(response.headers.get("content-type"))) {
+    await cancelResponseBody(response, "discarding API error body");
+    return "";
+  }
+  if (Number(response.headers.get("content-length")) > API_ERROR_MAX_BYTES) {
+    await cancelResponseBody(response, "discarding API error body");
+    return "";
+  }
   try {
-    return new TextDecoder().decode(await readBoundedResponseBytes(response, 64 * 1024, null));
+    return new TextDecoder().decode(
+      await readBoundedResponseBytes(response, API_ERROR_MAX_BYTES, null),
+    );
   } catch {
     return "";
   }
 }
 
+function isJsonContentType(value: string | null): boolean {
+  return /^(application\/json|[^;]+\+json)\s*(;|$)/i.test(value ?? "");
+}
+
+function isMutationMethod(method: string): boolean {
+  return method !== "GET" && method !== "HEAD" && method !== "OPTIONS";
+}
+
+function mutationTransportError(correlationId: string): OpenGeniApiError {
+  return new OpenGeniApiError(0, "", {
+    code: "network_error",
+    retryable: true,
+    correlationId,
+    outcomeUnknown: true,
+    mutation: true,
+    displayMessage: "OpenGeni could not confirm the request — reconcile before retrying.",
+  });
+}
+
+async function sha256ForUpload(body: Blob | ArrayBuffer | string): Promise<string> {
+  const bytes =
+    typeof body === "string"
+      ? new TextEncoder().encode(body)
+      : body instanceof Blob
+        ? new Uint8Array(await body.arrayBuffer())
+        : new Uint8Array(body);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
 async function cancelResponseBody(response: Response, reason: string): Promise<void> {
   await response.body?.cancel(reason).catch(() => undefined);
 }