@opengeni/sdk 0.25.0 → 0.25.5

package/package.json

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

@@ -33,6 +33,8 @@ import type {
   CapabilityCatalogResponse,
   CapabilityInstallation,
   AddDocumentRequest,
+  CreateKnowledgeDropRequest,
+  MoveDocumentRequest,
   ClientConfig,
   WorkspaceModelCatalogResponse,
   ClientSessionEventInput,
@@ -170,6 +172,7 @@ import type {
   UpdateScheduledTaskRequest,
   UpdateSessionGoalRequest,
   UpdateSessionRequest,
+  UpdateSessionToolPolicyRequest,
   UpdateVariableSetRequest,
   UpdateRigRequest,
   UpdateWorkspaceMemberRequest,
@@ -196,6 +199,7 @@ import type {
 import {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
+  OPENGENI_CORRELATION_HEADER,
   RETAINED_OUTPUT_MAX_PAGE_BYTES,
 } from "./types";
 
@@ -323,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
@@ -396,7 +413,13 @@ export class OpenGeniClient {
       );
     } catch (error) {
       if (error instanceof OpenGeniApiError && error.status === 410) {
-        throw new OpenGeniSessionListCursorError(error.status, error.body);
+        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;
     }
@@ -650,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) } : {}),
@@ -676,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;
@@ -880,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");
@@ -1033,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) } : {}),
@@ -1040,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");
@@ -1087,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");
     }
@@ -2013,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);
   }
@@ -2048,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 } : {}),
         },
@@ -2067,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");
@@ -2157,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,
@@ -2459,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 });
   }
@@ -2574,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 } : {}),
     };
   }
 
@@ -2744,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 });
     }
   }
 }
@@ -2786,6 +2877,75 @@ function assertApiContractResponse(response: Response): void {
   }
 }
 
+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 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, 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"
@@ -2797,22 +2957,6 @@ async function sha256ForUpload(body: Blob | ArrayBuffer | string): Promise<strin
   return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 
-async function safeText(response: Response): Promise<string> {
-  try {
-    return await response.text();
-  } catch {
-    return "";
-  }
-}
-
-async function safeBoundedText(response: Response): Promise<string> {
-  try {
-    return new TextDecoder().decode(await readBoundedResponseBytes(response, 64 * 1024, null));
-  } catch {
-    return "";
-  }
-}
-
 async function cancelResponseBody(response: Response, reason: string): Promise<void> {
   await response.body?.cancel(reason).catch(() => undefined);
 }

package/src/errors.ts

@@ -2,33 +2,97 @@
 export class OpenGeniApiError extends Error {
   readonly status: number;
   readonly code: string | undefined;
+  readonly retryable: boolean;
+  readonly correlationId: string | undefined;
+  /** True only when an uncontrolled transport failed after a mutation may have been accepted. */
+  readonly outcomeUnknown: boolean;
   readonly body: string;
 
-  constructor(status: number, body: string) {
+  constructor(
+    status: number,
+    body: string,
+    options: {
+      code?: string | undefined;
+      retryable?: boolean | undefined;
+      correlationId?: string | undefined;
+      outcomeUnknown?: boolean | undefined;
+      displayMessage?: string | undefined;
+      mutation?: boolean | undefined;
+    } = {},
+  ) {
     const decoded = decodeApiErrorBody(body);
-    super(`OpenGeni API ${status}: ${decoded.message ?? (body || "(empty body)")}`);
+    const correlationId = decoded?.requestId ?? boundedCorrelationId(options.correlationId);
+    const gatewayFailure = status >= 502 && status <= 504;
+    const fromResponse = options.mutation !== undefined;
+    const message = decoded?.message ?? (fromResponse ? "Request failed." : body || "(empty body)");
+    const displayMessage =
+      options.displayMessage ??
+      (gatewayFailure && fromResponse
+        ? "OpenGeni is temporarily unavailable — retry."
+        : `OpenGeni API ${status}: ${message}`);
+    super(correlationId ? `${displayMessage} Reference: ${correlationId}.` : displayMessage);
     this.name = "OpenGeniApiError";
     this.status = status;
-    this.code = decoded.code;
-    this.body = body;
+    this.code =
+      options.code ??
+      decoded?.code ??
+      (gatewayFailure && fromResponse ? "upstream_unavailable" : undefined);
+    this.retryable = options.retryable ?? decoded?.retryable ?? retryableApiStatus(status);
+    this.correlationId = correlationId;
+    this.outcomeUnknown =
+      options.outcomeUnknown ?? (gatewayFailure && !!options.mutation && !decoded);
+    this.body = !fromResponse || decoded ? body : "";
   }
 }
 
-function decodeApiErrorBody(body: string): { code?: string; message?: string } {
-  if (!body) return {};
+function decodeApiErrorBody(body: string): {
+  code: string | undefined;
+  message: string | undefined;
+  requestId: string | undefined;
+  retryable: boolean | undefined;
+} | null {
+  if (!body) return null;
   try {
     const decoded: unknown = JSON.parse(body);
-    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) return {};
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) return null;
     const record = decoded as Record<string, unknown>;
+    const nested =
+      record.error && typeof record.error === "object" && !Array.isArray(record.error)
+        ? (record.error as Record<string, unknown>)
+        : record;
+    const code = boundedApiField(nested.code);
+    const message = boundedApiField(nested.message);
+    const requestId = boundedCorrelationId(nested.requestId);
+    const retryable = typeof nested.retryable === "boolean" ? nested.retryable : undefined;
+    if (!code && !message && !requestId && retryable === undefined) return null;
     return {
-      ...(typeof record.code === "string" && record.code ? { code: record.code } : {}),
-      ...(typeof record.message === "string" && record.message ? { message: record.message } : {}),
+      code,
+      message,
+      requestId,
+      retryable,
     };
   } catch {
-    return {};
+    return null;
   }
 }
 
+function boundedApiField(value: unknown): string | undefined {
+  if (typeof value !== "string") return;
+  const bytes = new TextEncoder().encode(value);
+  return bytes.byteLength <= 512 ? value : new TextDecoder().decode(bytes.slice(0, 512));
+}
+
+function retryableApiStatus(status: number): boolean {
+  return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;
+}
+
+function boundedCorrelationId(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length > 128 || !/^[\w.:-]+$/.test(value)) {
+    return;
+  }
+  return value;
+}
+
 /** A short-lived session-list snapshot cursor can no longer be continued. */
 export class OpenGeniSessionListCursorError extends OpenGeniApiError {}
 
@@ -67,14 +131,6 @@ export function isAbortError(error: unknown): boolean {
  * permanent and surface to the caller instead.
  */
 export function isRetryableStreamError(error: unknown): boolean {
-  if (error instanceof OpenGeniApiError) {
-    return (
-      error.status === 408 ||
-      error.status === 409 ||
-      error.status === 425 ||
-      error.status === 429 ||
-      error.status >= 500
-    );
-  }
+  if (error instanceof OpenGeniApiError) return error.retryable;
   return error instanceof TypeError;
 }

package/src/index.ts

@@ -86,6 +86,7 @@ export {
   KNOWN_USAGE_EVENT_TYPES,
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
+  OPENGENI_CORRELATION_HEADER,
   RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
   RETAINED_OUTPUT_MAX_PAGE_BYTES,
   SESSION_EVENT_TYPES,
@@ -175,6 +176,7 @@ export type {
   CreateFileUploadResponse,
   CreateGitHubAppManifestRequest,
   CreateGitHubAppManifestResponse,
+  CreateKnowledgeDropRequest,
   CreateKnowledgeMemoryRequest,
   CreateScheduledTaskRequest,
   CreateSessionRequest,
@@ -184,11 +186,15 @@ export type {
   DiscoverMcpCapabilitiesResponse,
   Document,
   DocumentBase,
+  DocumentCuration,
+  DocumentCurationStatus,
   DocumentSearchMode,
   DocumentSearchRequest,
   DocumentSearchResponse,
   DocumentSearchResult,
   DocumentStatus,
+  DocumentVisibility,
+  MoveDocumentRequest,
   EnableCapabilityRequest,
   EnablePackRequest,
   Entitlements,
@@ -206,7 +212,9 @@ export type {
   FileUploadData,
   GetPackResponse,
   GitHubAppInfo,
+  GitHubBindingStatus,
   GitHubInstallationBinding,
+  GitHubInstallationLifecycle,
   GitHubRepositoriesResponse,
   GitHubRepository,
   GitHubRepositoryScope,
@@ -411,6 +419,7 @@ export type {
   UpdateSessionMcpApprovalPolicyResponse,
   UpdateSessionPinRequest,
   UpdateSessionRequest,
+  UpdateSessionToolPolicyRequest,
   UpdateVariableSetRequest,
   UpdateWorkspaceEnvironmentRequest,
   UpdateWorkspaceMemberRequest,