@opengeni/sdk 0.25.0 → 0.25.5

package/dist/index.js

@@ -2,30 +2,64 @@
 var OpenGeniApiError = class extends Error {
   status;
   code;
+  retryable;
+  correlationId;
+  /** True only when an uncontrolled transport failed after a mutation may have been accepted. */
+  outcomeUnknown;
   body;
-  constructor(status, body) {
+  constructor(status, body, options = {}) {
     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 !== void 0;
+    const message = decoded?.message ?? (fromResponse ? "Request failed." : body || "(empty body)");
+    const displayMessage = options.displayMessage ?? (gatewayFailure && fromResponse ? "OpenGeni is temporarily unavailable \u2014 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" : void 0);
+    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) {
-  if (!body) return {};
+  if (!body) return null;
   try {
     const decoded = 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;
+    const nested = record.error && typeof record.error === "object" && !Array.isArray(record.error) ? record.error : record;
+    const code = boundedApiField(nested.code);
+    const message = boundedApiField(nested.message);
+    const requestId = boundedCorrelationId(nested.requestId);
+    const retryable = typeof nested.retryable === "boolean" ? nested.retryable : void 0;
+    if (!code && !message && !requestId && retryable === void 0) 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) {
+  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) {
+  return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;
+}
+function boundedCorrelationId(value) {
+  if (typeof value !== "string" || value.length > 128 || !/^[\w.:-]+$/.test(value)) {
+    return;
+  }
+  return value;
+}
 var OpenGeniSessionListCursorError = class extends OpenGeniApiError {
 };
 var OpenGeniApiContractMismatchError = class extends Error {
@@ -48,9 +82,7 @@ function isAbortError(error) {
   return error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
 }
 function isRetryableStreamError(error) {
-  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;
 }
 
@@ -391,6 +423,7 @@ var SESSION_EVENT_TYPES = [
   "terminal.pty.exited",
   "session.title_set",
   "session.mcp.approval_policy.updated",
+  "session.tool_policy.updated",
   // Multi-account Codex (P1): the session's inference account changed.
   "codex.account.switched",
   // credential allocator metadata-only per-turn credential selection audit.
@@ -472,6 +505,7 @@ var KNOWN_PERMISSIONS = [
 ];
 var OPENGENI_API_CONTRACT_REVISION = "2026-07-turn-instructions-v1";
 var OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract";
+var OPENGENI_CORRELATION_HEADER = "x-opengeni-correlation-id";
 var RETAINED_OUTPUT_DEFAULT_PAGE_BYTES = 256 * 1024;
 var RETAINED_OUTPUT_MAX_PAGE_BYTES = 1024 * 1024;
 var KNOWN_USAGE_EVENT_TYPES = [
@@ -540,6 +574,14 @@ var OpenGeniClient = class {
       request
     );
   }
+  /** Replace the durable tool policy or explicitly adopt workspace defaults. */
+  async updateSessionToolPolicy(workspaceId, sessionId, request) {
+    return await this.requestJson(
+      "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
@@ -583,7 +625,13 @@ var OpenGeniClient = class {
       );
     } 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 \u2014 refresh and try again."
+        });
       }
       throw error;
     }
@@ -758,6 +806,7 @@ var OpenGeniClient = class {
       throw new TypeError("resultMode=compact requires latest");
     }
     const listOptions = options.resultMode === "compact" ? null : options;
+    const correlationId = crypto.randomUUID();
     const response = await this.fetchImpl(
       this.url(`/v1/workspaces/${workspaceId}/sessions/${sessionId}/events`, {
         ...listOptions?.after !== void 0 ? { after: String(listOptions.after) } : {},
@@ -776,11 +825,14 @@ var OpenGeniClient = class {
       }),
       {
         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;
@@ -908,14 +960,15 @@ var OpenGeniClient = class {
     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");
@@ -997,6 +1050,7 @@ var OpenGeniClient = class {
   }
   /** Count/byte-bounded page plus an explicit continuation cursor. */
   async listWorkspaceControlEventPage(workspaceId, options = {}) {
+    const correlationId = crypto.randomUUID();
     const response = await this.fetchImpl(
       this.url(`/v1/workspaces/${workspaceId}/control-events`, {
         ...options.after !== void 0 ? { after: String(options.after) } : {},
@@ -1004,13 +1058,14 @@ var OpenGeniClient = class {
       }),
       {
         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();
     const bytesHeader = response.headers.get("X-OpenGeni-Page-Bytes");
     const nextHeader = response.headers.get("X-OpenGeni-Next-After");
@@ -1035,18 +1090,21 @@ var OpenGeniClient = class {
     };
   }
   async openWorkspaceControlEventStream(workspaceId, options = {}) {
+    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");
     }
@@ -1684,7 +1742,7 @@ var OpenGeniClient = class {
       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);
   }
@@ -1709,12 +1767,13 @@ var OpenGeniClient = class {
     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 } : {}
         },
@@ -1728,7 +1787,7 @@ var OpenGeniClient = class {
       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");
@@ -1800,6 +1859,30 @@ var OpenGeniClient = class {
       `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents`
     );
   }
+  /**
+   * 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, request) {
+    return await this.requestJson(
+      "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, documentId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/documents/${documentId}/move`,
+      request
+    );
+  }
   /** Retry indexing for a failed document. */
   async reindexDocument(workspaceId, baseId, documentId) {
     return await this.requestJson(
@@ -2010,14 +2093,11 @@ var OpenGeniClient = class {
     return logoAssetPath ? `${this.baseUrl}/v1/${logoAssetPath}` : null;
   }
   // --- 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) {
     return await this.requestJson("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, state) {
     return this.url(`/v1/workspaces/${workspaceId}/github/connect`, { state });
   }
@@ -2099,12 +2179,13 @@ var OpenGeniClient = class {
     return await this.requestJson("POST", "/v1/billing/checkout", request);
   }
   // --- Internals -------------------------------------------------------------
-  headers() {
+  headers(correlationId) {
     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
+      [OPENGENI_API_CONTRACT_HEADER]: OPENGENI_API_CONTRACT_REVISION,
+      ...correlationId ? { [OPENGENI_CORRELATION_HEADER]: correlationId } : {}
     };
   }
   url(path, query = {}) {
@@ -2220,36 +2301,62 @@ var OpenGeniClient = class {
     );
   }
   async requestJson(method, path, body, query = {}, options = {}) {
-    const response = await this.fetchImpl(this.url(path, query), {
-      method,
-      headers: {
-        ...this.headers(),
-        Accept: "application/json",
-        ...body !== void 0 ? { "Content-Type": "application/json" } : {}
-      },
-      ...body !== void 0 ? { body: JSON.stringify(body) } : {},
-      ...options.signal ? { signal: options.signal } : {}
-    });
+    const correlationId = crypto.randomUUID();
+    let response;
+    try {
+      response = await this.fetchImpl(this.url(path, query), {
+        method,
+        headers: {
+          ...this.headers(correlationId),
+          Accept: "application/json",
+          ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+        },
+        ...body !== void 0 ? { 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();
+    } catch (error) {
+      if (isMutationMethod(method)) {
+        throw mutationTransportError(correlationId);
+      }
+      throw error;
     }
-    return await response.json();
   }
   /** Like `requestJson` for endpoints that respond with no body (204). */
   async requestVoid(method, path, body) {
-    const response = await this.fetchImpl(this.url(path), {
-      method,
-      headers: {
-        ...this.headers(),
-        Accept: "application/json",
-        ...body !== void 0 ? { "Content-Type": "application/json" } : {}
-      },
-      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
-    });
+    const correlationId = crypto.randomUUID();
+    let response;
+    try {
+      response = await this.fetchImpl(this.url(path), {
+        method,
+        headers: {
+          ...this.headers(correlationId),
+          Accept: "application/json",
+          ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+        },
+        ...body !== void 0 ? { 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 });
     }
   }
 };
@@ -2259,25 +2366,62 @@ function assertApiContractResponse(response) {
     throw new OpenGeniApiContractMismatchError(OPENGENI_API_CONTRACT_REVISION, actual);
   }
 }
-async function sha256ForUpload(body) {
-  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("");
+var API_ERROR_MAX_BYTES = 16 * 1024;
+async function apiErrorFromResponse(response, context) {
+  return new OpenGeniApiError(response.status, await readBoundedJsonErrorBody(response), {
+    correlationId: response.headers.get(OPENGENI_CORRELATION_HEADER) ?? context.correlationId,
+    mutation: isMutationMethod(context.method)
+  });
 }
-async function safeText(response) {
-  try {
-    return await response.text();
-  } catch {
+async function assertJsonResponse(response, context) {
+  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 \u2014 retry."
+  });
+}
+async function readBoundedJsonErrorBody(response) {
+  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 "";
   }
-}
-async function safeBoundedText(response) {
   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) {
+  return /^(application\/json|[^;]+\+json)\s*(;|$)/i.test(value ?? "");
+}
+function isMutationMethod(method) {
+  return method !== "GET" && method !== "HEAD" && method !== "OPTIONS";
+}
+function mutationTransportError(correlationId) {
+  return new OpenGeniApiError(0, "", {
+    code: "network_error",
+    retryable: true,
+    correlationId,
+    outcomeUnknown: true,
+    mutation: true,
+    displayMessage: "OpenGeni could not confirm the request \u2014 reconcile before retrying."
+  });
+}
+async function sha256ForUpload(body) {
+  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, reason) {
   await response.body?.cancel(reason).catch(() => void 0);
 }
@@ -2729,6 +2873,7 @@ export {
   KNOWN_USAGE_EVENT_TYPES,
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
+  OPENGENI_CORRELATION_HEADER,
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
   OpenGeniClient,