@opengeni/sdk 0.52.1 → 1.0.0

package/src/errors.ts

@@ -29,7 +29,7 @@ export class OpenGeniApiError extends Error {
     const displayMessage =
       options.displayMessage ??
       (gatewayFailure && fromResponse
-        ? (decoded?.message ?? "OpenGeni is temporarily unavailable — retry.")
+        ? (decoded?.message ?? "Opengeni is temporarily unavailable — retry.")
         : `OpenGeni API ${status}: ${message}`);
     super(correlationId ? `${displayMessage} Reference: ${correlationId}.` : displayMessage);
     this.name = "OpenGeniApiError";
@@ -41,17 +41,118 @@ export class OpenGeniApiError extends Error {
     this.retryable = options.retryable ?? decoded?.retryable ?? retryableApiStatus(status);
     this.correlationId = correlationId;
     this.outcomeUnknown =
-      options.outcomeUnknown ?? (gatewayFailure && !!options.mutation && !decoded);
+      options.outcomeUnknown ??
+      decoded?.outcomeUnknown ??
+      (gatewayFailure && !!options.mutation && !decoded);
     this.body = !fromResponse || decoded ? body : "";
     this.details = decoded?.details;
   }
 }
 
+/** 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;
+  }
+}
+
+/** 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";
+
+/**
+ * A browser operation requires secure-context-only platform capabilities.
+ * Callers may key UI behavior on the stable `secure_context_required` code;
+ * `reason` exists only to keep the human guidance truthful.
+ */
+export class OpenGeniSecureContextRequiredError extends Error {
+  readonly code = "secure_context_required" as const;
+  readonly retryable = false;
+  readonly reason: OpenGeniSecureContextRequiredReason;
+
+  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 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";
+    this.reason = reason;
+  }
+}
+
 function decodeApiErrorBody(body: string): {
   code: string | undefined;
   message: string | undefined;
   requestId: string | undefined;
   retryable: boolean | undefined;
+  outcomeUnknown: boolean | undefined;
   details: Record<string, unknown> | undefined;
 } | null {
   if (!body) return null;
@@ -67,13 +168,24 @@ function decodeApiErrorBody(body: string): {
     const message = boundedApiField(nested.message);
     const requestId = boundedCorrelationId(nested.requestId);
     const retryable = typeof nested.retryable === "boolean" ? nested.retryable : undefined;
+    const outcomeUnknown =
+      typeof nested.outcomeUnknown === "boolean" ? nested.outcomeUnknown : undefined;
     const details = boundedApiDetails(nested.details);
-    if (!code && !message && !requestId && retryable === undefined && !details) return null;
+    if (
+      !code &&
+      !message &&
+      !requestId &&
+      retryable === undefined &&
+      outcomeUnknown === undefined &&
+      !details
+    )
+      return null;
     return {
       code,
       message,
       requestId,
       retryable,
+      outcomeUnknown,
       details,
     };
   } catch {
@@ -114,7 +226,7 @@ function boundedCorrelationId(value: unknown): string | undefined {
   return value;
 }
 
-/** A short-lived session-list snapshot cursor can no longer be continued. */
+/** A legacy short-lived session-list snapshot cursor can no longer be continued. */
 export class OpenGeniSessionListCursorError extends OpenGeniApiError {}
 
 /** The browser bundle and API disagree about their state-changing wire contract. */
@@ -138,6 +250,75 @@ 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.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") ||

package/src/feedback.ts

@@ -0,0 +1,20 @@
+export type FeedbackSentiment = "positive" | "negative";
+export type CreateFeedbackRequest = {
+  idempotencyKey: string;
+  sessionId?: string | undefined;
+  turnId?: string | undefined;
+  sentiment?: FeedbackSentiment | undefined;
+  comment?: string | undefined;
+};
+export type Feedback = {
+  id: string;
+  workspaceId: string;
+  subjectId: string;
+  principalKind: string | null;
+  sessionId: string | null;
+  turnId: string | null;
+  sentiment: FeedbackSentiment | null;
+  comment: string | null;
+  createdAt: string;
+};
+export type FeedbackSubmissionResponse = { feedback: Feedback; replayed: boolean };