@opengeni/sdk 0.25.0 → 0.26.0

package/package.json

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

package/src/client.ts

@@ -33,6 +33,8 @@ import type {
   CapabilityCatalogResponse,
   CapabilityInstallation,
   AddDocumentRequest,
+  CreateKnowledgeDropRequest,
+  MoveDocumentRequest,
   ClientConfig,
   WorkspaceModelCatalogResponse,
   ClientSessionEventInput,
@@ -44,6 +46,7 @@ import type {
   CreateCapabilityCatalogItemRequest,
   CreateCheckoutRequest,
   CreateCheckoutResponse,
+  ConnectOpenGeniSlackBotRequest,
   CreateConnectionRequest,
   CreateDocumentBaseRequest,
   CreateFileUploadRequest,
@@ -170,6 +173,7 @@ import type {
   UpdateScheduledTaskRequest,
   UpdateSessionGoalRequest,
   UpdateSessionRequest,
+  UpdateSessionToolPolicyRequest,
   UpdateVariableSetRequest,
   UpdateRigRequest,
   UpdateWorkspaceMemberRequest,
@@ -193,9 +197,22 @@ import type {
   OAuthStartRequest,
   OAuthStartResponse,
 } from "./types";
+import type {
+  ActivateWorkspaceInstructionPolicyRequest,
+  CreateWorkspaceInstructionPolicyDraftRequest,
+  ImportLegacyWorkspaceInstructionPolicyDraftRequest,
+  RollbackWorkspaceInstructionPolicyRequest,
+  WorkspaceInstructionPolicyActivationResponse,
+  WorkspaceInstructionPolicyDiffRequest,
+  WorkspaceInstructionPolicyDiffResponse,
+  WorkspaceInstructionPolicyListOptions,
+  WorkspaceInstructionPolicyListResponse,
+  WorkspaceInstructionPolicyRevision,
+} from "./workspace-instruction-policies";
 import {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
+  OPENGENI_CORRELATION_HEADER,
   RETAINED_OUTPUT_MAX_PAGE_BYTES,
 } from "./types";
 
@@ -323,6 +340,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 +426,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 +686,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 +713,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 +920,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 +1074,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 +1082,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 +1130,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");
     }
@@ -1580,6 +1626,96 @@ export class OpenGeniClient {
     return await this.requestJson<Workspace>("PATCH", `/v1/workspaces/${workspaceId}`, request);
   }
 
+  /** Inspect immutable instruction-policy history, active heads, and activation audit evidence. */
+  async listWorkspaceInstructionPolicies(
+    workspaceId: string,
+    options: WorkspaceInstructionPolicyListOptions = {},
+  ): Promise<WorkspaceInstructionPolicyListResponse> {
+    const params = new URLSearchParams();
+    if (options.kind !== undefined) params.set("kind", options.kind);
+    if (options.scope !== undefined) params.set("scope", options.scope);
+    if (options.roleKey !== undefined) params.set("roleKey", options.roleKey);
+    if (options.afterRevision !== undefined) {
+      params.set("afterRevision", String(options.afterRevision));
+    }
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    const query = params.toString();
+    return await this.requestJson<WorkspaceInstructionPolicyListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/instruction-policies${query ? `?${query}` : ""}`,
+    );
+  }
+
+  async getWorkspaceInstructionPolicyRevision(
+    workspaceId: string,
+    revisionId: string,
+  ): Promise<WorkspaceInstructionPolicyRevision> {
+    return await this.requestJson<WorkspaceInstructionPolicyRevision>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/instruction-policies/${encodeURIComponent(revisionId)}`,
+    );
+  }
+
+  async createWorkspaceInstructionPolicyDraft(
+    workspaceId: string,
+    request: CreateWorkspaceInstructionPolicyDraftRequest,
+  ): Promise<WorkspaceInstructionPolicyRevision> {
+    return await this.requestJson<WorkspaceInstructionPolicyRevision>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/instruction-policies/drafts`,
+      request,
+    );
+  }
+
+  /** Import the stored legacy workspace override as an inactive charter draft. */
+  async importLegacyWorkspaceInstructionPolicyDraft(
+    workspaceId: string,
+    request: ImportLegacyWorkspaceInstructionPolicyDraftRequest = {},
+  ): Promise<WorkspaceInstructionPolicyRevision> {
+    return await this.requestJson<WorkspaceInstructionPolicyRevision>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/instruction-policies/import-legacy`,
+      request,
+    );
+  }
+
+  async diffWorkspaceInstructionPolicyRevisions(
+    workspaceId: string,
+    request: WorkspaceInstructionPolicyDiffRequest,
+  ): Promise<WorkspaceInstructionPolicyDiffResponse> {
+    const params = new URLSearchParams({
+      fromRevisionId: request.fromRevisionId,
+      toRevisionId: request.toRevisionId,
+    });
+    return await this.requestJson<WorkspaceInstructionPolicyDiffResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/instruction-policies/diff?${params}`,
+    );
+  }
+
+  async activateWorkspaceInstructionPolicyRevision(
+    workspaceId: string,
+    revisionId: string,
+    request: ActivateWorkspaceInstructionPolicyRequest,
+  ): Promise<WorkspaceInstructionPolicyActivationResponse> {
+    return await this.requestJson<WorkspaceInstructionPolicyActivationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/instruction-policies/${encodeURIComponent(revisionId)}/activate`,
+      request,
+    );
+  }
+
+  async rollbackWorkspaceInstructionPolicyRevision(
+    workspaceId: string,
+    request: RollbackWorkspaceInstructionPolicyRequest,
+  ): Promise<WorkspaceInstructionPolicyActivationResponse> {
+    return await this.requestJson<WorkspaceInstructionPolicyActivationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/instruction-policies/rollback`,
+      request,
+    );
+  }
+
   /**
    * Delete a workspace and everything in it. Refused (409) for the account's
    * only workspace and while it still has a running session. Irreversible.
@@ -2013,7 +2149,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 +2184,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 +2204,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 +2294,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,
@@ -2419,6 +2589,19 @@ export class OpenGeniClient {
     return response.connection;
   }
 
+  /** Validate and store/reinstall the workspace-shared OpenGeni Slack bot credential. */
+  async connectOpenGeniSlackBot(
+    workspaceId: string,
+    request: ConnectOpenGeniSlackBotRequest,
+  ): Promise<ConnectionMetadata> {
+    const response = await this.requestJson<ConnectionResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/connections/slack-bot`,
+      request,
+    );
+    return response.connection;
+  }
+
   async updateConnection(
     workspaceId: string,
     connectionId: string,
@@ -2459,15 +2642,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 +2754,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 +2925,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 +2993,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 +3073,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);
 }