@opengeni/sdk 3.3.2-canary.1 → 3.4.0

package/src/errors.ts

@@ -1,4 +1,9 @@
-/** Error for a non-2xx OpenGeni API response. */
+import {
+  parseSessionUsageLimitReachedRefusal,
+  type ParsedSessionUsageLimitReachedRefusal,
+} from "@opengeni/contracts/session-usage-limit-refusal";
+
+/** Error for a non-2xx Opengeni API response. */
 export class OpenGeniApiError extends Error {
   readonly status: number;
   readonly code: string | undefined;
@@ -29,8 +34,8 @@ export class OpenGeniApiError extends Error {
     const displayMessage =
       options.displayMessage ??
       (gatewayFailure && fromResponse
-        ? (decoded?.message ?? "OpenGeni is temporarily unavailable — retry.")
-        : `OpenGeni API ${status}: ${message}`);
+        ? (decoded?.message ?? "Opengeni is temporarily unavailable — retry.")
+        : `Opengeni API ${status}: ${message}`);
     super(correlationId ? `${displayMessage} Reference: ${correlationId}.` : displayMessage);
     this.name = "OpenGeniApiError";
     this.status = status;
@@ -49,6 +54,200 @@ export class OpenGeniApiError extends Error {
   }
 }
 
+/** Deployment or organization setup must be completed before private chats can be created. */
+export class OpenGeniSetupError extends OpenGeniApiError {
+  constructor(error: OpenGeniApiError) {
+    super(error.status, error.body, {
+      code: "OPENGENI_SETUP_REQUIRED",
+      retryable: false,
+      correlationId: error.correlationId,
+      displayMessage:
+        "Private chats require organization_private_session_settings.enabled (migration 0323). " +
+        "An organization owner or admin can enable Only me chats in the web app under Organization settings > Security & data, " +
+        "or use updateOrganizationPrivateSessionSettings from @opengeni/sdk/organization-private-session-settings " +
+        "with enabled: true, the current expectedVersion and a stable operationId " +
+        "(PATCH /v1/organizations/:organizationId/private-session-settings; an organization key needs workspace:admin). " +
+        "If platform readiness is unavailable, ask the deployment operator to activate session tenancy first.",
+    });
+    this.name = "OpenGeniSetupError";
+  }
+}
+
+/** A settled usage ceiling refuses the next call; retry after reset or an authorized grant. */
+export class OpenGeniAllowanceExhaustedError extends OpenGeniApiError {
+  readonly scope: "workspace" | "member";
+  readonly resetsAt: string | null;
+  readonly subjectId: string | undefined;
+
+  constructor(
+    status: number,
+    body: string,
+    options: ConstructorParameters<typeof OpenGeniApiError>[2] = {},
+  ) {
+    super(status, body, {
+      ...options,
+      code: "allowance_exhausted",
+      retryable: false,
+      outcomeUnknown: false,
+    });
+    this.name = "OpenGeniAllowanceExhaustedError";
+    const refusal = allowanceExhaustedFields(body);
+    this.scope = refusal?.scope ?? "workspace";
+    this.resetsAt = refusal?.resetsAt ?? null;
+    this.subjectId = refusal?.subjectId;
+  }
+}
+
+/**
+ * The task's root usage limit is reached: recorded API-equivalent model usage
+ * is at or above the limit. Not a credit or billing failure and not retryable
+ * by waiting; a person can raise or remove the limit, then send again.
+ */
+export class OpenGeniSessionUsageLimitReachedError extends OpenGeniApiError {
+  readonly rootSessionId: string | undefined;
+  readonly limitMicros: number | undefined;
+  readonly usedMicros: number | undefined;
+
+  constructor(
+    status: number,
+    body: string,
+    options: ConstructorParameters<typeof OpenGeniApiError>[2] = {},
+  ) {
+    super(status, body, {
+      ...options,
+      code: "session_usage_limit_reached",
+      retryable: false,
+      outcomeUnknown: false,
+    });
+    this.name = "OpenGeniSessionUsageLimitReachedError";
+    const refusal = sessionUsageLimitReachedFields(body);
+    this.rootSessionId = refusal?.rootSessionId;
+    this.limitMicros = refusal?.limitMicros;
+    this.usedMicros = refusal?.usedMicros;
+  }
+}
+
+/**
+ * The server did not accept or confirm a requested task usage limit, so it
+ * predates usage limits (or limits are not enabled there). `sessionId` is null
+ * when the server rejected the create before creating anything; otherwise the
+ * session exists without a confirmed limit and no initial work was started by
+ * this SDK's request (an older server rejects it up front).
+ */
+export class OpenGeniSessionUsageLimitUnsupportedError extends Error {
+  readonly code = "session_usage_limit_unsupported";
+  readonly sessionId: string | null;
+
+  constructor(message: string, options: { sessionId?: string | null; cause?: unknown } = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "OpenGeniSessionUsageLimitUnsupportedError";
+    this.sessionId = options.sessionId ?? null;
+  }
+}
+
+/**
+ * True only when a create was refused because the server rejected the
+ * `startMode` field itself: servers that predate usage limits accept only
+ * `realtime` there. Matches the session create route's 422 validation
+ * envelope (`Invalid session create request: <fields> failed schema
+ * validation`) and a 400 request-body envelope whose issues name `startMode`.
+ * Any other validation error stays an ordinary API error.
+ */
+export function rejectsStartModeField(error: OpenGeniApiError): boolean {
+  if (error.status !== 400 && error.status !== 422) return false;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(error.body);
+  } catch {
+    return false;
+  }
+  if (!parsed || typeof parsed !== "object") return false;
+  const record = parsed as Record<string, unknown>;
+  const envelope =
+    record.error && typeof record.error === "object"
+      ? (record.error as Record<string, unknown>)
+      : record;
+  const message = typeof envelope.message === "string" ? envelope.message : "";
+  const fields = /^Invalid session create request: (.+) failed schema validation$/.exec(message);
+  if (
+    envelope.code === "INVALID_SESSION_CREATE_REQUEST" &&
+    fields?.[1]?.split(/,\s*/).includes("startMode")
+  ) {
+    return true;
+  }
+  const details =
+    envelope.details && typeof envelope.details === "object"
+      ? (envelope.details as Record<string, unknown>)
+      : null;
+  const issues = Array.isArray(details?.issues) ? details.issues : [];
+  return issues.some((issue) => {
+    if (!issue || typeof issue !== "object") return false;
+    const path = (issue as Record<string, unknown>).path;
+    return (
+      path === "startMode" || (Array.isArray(path) && path.length === 1 && path[0] === "startMode")
+    );
+  });
+}
+
+/** The committed limit differs from the one requested: never report success. */
+export function sessionUsageLimitNotConfirmed(
+  sessionId: string,
+): OpenGeniSessionUsageLimitUnsupportedError {
+  return new OpenGeniSessionUsageLimitUnsupportedError(
+    "The server did not confirm the requested usage limit; it may not support usage limits. Read the limit again before relying on it.",
+    { sessionId },
+  );
+}
+
+/** Parse a session usage limit refusal from an API error envelope body. */
+export function sessionUsageLimitReachedFields(
+  body: string,
+): ParsedSessionUsageLimitReachedRefusal | null {
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const root = parsed as Record<string, unknown>;
+    return parseSessionUsageLimitReachedRefusal(
+      root.error && typeof root.error === "object" && !Array.isArray(root.error)
+        ? root.error
+        : root,
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Accept both the API error envelope and the standalone admission refusal. */
+export function allowanceExhaustedFields(body: string): {
+  scope: "workspace" | "member";
+  resetsAt: string | null;
+  subjectId?: string;
+} | null {
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const root = parsed as Record<string, unknown>;
+    const error =
+      root.error && typeof root.error === "object" && !Array.isArray(root.error)
+        ? (root.error as Record<string, unknown>)
+        : root;
+    if (error.code !== "allowance_exhausted") return null;
+    const fields =
+      error.details && typeof error.details === "object" && !Array.isArray(error.details)
+        ? (error.details as Record<string, unknown>)
+        : error;
+    if (fields.scope !== "workspace" && fields.scope !== "member") return null;
+    if (fields.resetsAt !== null && typeof fields.resetsAt !== "string") return null;
+    return {
+      scope: fields.scope,
+      resetsAt: fields.resetsAt,
+      ...(typeof fields.subjectId === "string" ? { subjectId: fields.subjectId } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
 export type OpenGeniSecureContextRequiredReason = "insecure_context" | "web_crypto_unavailable";
 
 /**
@@ -64,7 +263,7 @@ export class OpenGeniSecureContextRequiredError extends Error {
   constructor(reason: OpenGeniSecureContextRequiredReason) {
     super(
       reason === "insecure_context"
-        ? "Couldn’t attach this file because OpenGeni is open over HTTP. Attachments require a secure HTTPS connection. Open the secure site or configure HTTPS for this deployment."
+        ? "Couldn’t attach this file because Opengeni is open over HTTP. Attachments require a secure HTTPS connection. Open the secure site or configure HTTPS for this deployment."
         : "Couldn’t attach this file because secure browser cryptography is unavailable. Attachments require HTTPS and Web Crypto support. Open a secure site in a supported browser or configure HTTPS for this deployment.",
     );
     this.name = "OpenGeniSecureContextRequiredError";
@@ -160,7 +359,7 @@ export class OpenGeniApiContractMismatchError extends Error {
   readonly actual: string;
 
   constructor(expected: string, actual: string) {
-    super(`OpenGeni API contract mismatch: client expects ${expected}, API serves ${actual}`);
+    super(`Opengeni API contract mismatch: client expects ${expected}, API serves ${actual}`);
     this.name = "OpenGeniApiContractMismatchError";
     this.expected = expected;
     this.actual = actual;
@@ -175,6 +374,83 @@ export class OpenGeniStreamError extends Error {
   }
 }
 
+/**
+ * Brand-neutral end-user copy for a failed SDK operation. Error.message, body,
+ * details and typed fields remain unchanged for diagnostics and host policy.
+ * Never use this to rewrite user, assistant or tool content.
+ */
+export function formatErrorMessage(
+  error: unknown,
+  fallback = "The request could not be completed.",
+): string {
+  if (error instanceof OpenGeniApiError) {
+    let message: string;
+    if (error.outcomeUnknown) {
+      message = "The request could not be confirmed. Check its status before retrying.";
+    } else if (
+      error instanceof OpenGeniSetupError ||
+      error.code === "OPENGENI_SETUP_REQUIRED" ||
+      error.code === "SESSION_TENANCY_NOT_ACTIVATED"
+    ) {
+      message = "Private conversations are unavailable. Ask an administrator to enable them.";
+    } else if (error.details?.code === "not_available_for_viewer") {
+      message = "This Site's assistant is not available for this viewer.";
+    } else if (error.details?.code === "site_budget_exhausted") {
+      message = "This Site's assistant has reached its usage limit for now.";
+    } else if (error.details?.code === "site_budget_busy") {
+      message = "This Site's assistant is busy. Try again in a moment.";
+    } else if (error.details?.code === "site_platform_brake_engaged") {
+      message = "This Site's assistant is paused for visitors right now.";
+    } else if (error.code === "allowance_exhausted") {
+      message = "Usage limit reached. Wait for the reset or ask an administrator for more usage.";
+    } else if (error instanceof OpenGeniSessionListCursorError) {
+      message = "The conversation list changed. Refresh and try again.";
+    } else if (error.status === 401) {
+      message = "Sign in to continue.";
+    } else if (error.status === 403) {
+      message = "You don’t have permission to do that.";
+    } else if (error.status === 404) {
+      message = "The requested item is unavailable.";
+    } else if (error.status === 402 || error.code === "payment_required") {
+      message = "There are not enough credits to continue.";
+    } else if (error.status === 429 || error.code === "rate_limited") {
+      message = error.retryable
+        ? "Too many requests. Wait a moment and try again."
+        : "This request is unavailable. Ask an administrator for help.";
+    } else if (error.status === 409) {
+      message = "The request conflicts with the current state. Refresh and try again.";
+    } else if (error.status === 400 || error.status === 422) {
+      message = "The request could not be accepted. Check your input and try again.";
+    } else if (error.status === 408 || error.status === 425 || error.status === 0) {
+      message = error.retryable
+        ? "The connection could not be completed. Try again later."
+        : fallback;
+    } else if (error.status >= 500) {
+      message = error.retryable
+        ? "The service is temporarily unavailable. Try again later."
+        : "The service is unavailable. Ask an administrator for help.";
+    } else {
+      message = fallback;
+    }
+    return error.correlationId ? `${message} Reference: ${error.correlationId}.` : message;
+  }
+  if (
+    error instanceof OpenGeniSecureContextRequiredError ||
+    (error instanceof Error && "code" in error && error.code === "secure_context_required")
+  ) {
+    return "reason" in error && error.reason === "insecure_context"
+      ? "Attachments require HTTPS. Open this page over a secure connection."
+      : "Attachments require secure browser cryptography. Use a supported browser over HTTPS.";
+  }
+  if (error instanceof OpenGeniApiContractMismatchError) {
+    return "This page is out of date. Reload it before trying again.";
+  }
+  if (error instanceof OpenGeniStreamError) {
+    return "The live connection could not be restored. Refresh to check the latest state.";
+  }
+  return fallback;
+}
+
 export function isAbortError(error: unknown): boolean {
   return (
     (error instanceof DOMException && error.name === "AbortError") ||