10xgraph-client 0.6.0 → 1.0.0-rc.2

package/src/errors.ts

@@ -20,6 +20,8 @@ export interface ApiErrorResponse {
     code: string;
     message: string;
     details: ErrorDetail[];
+    /** Present on 429 replies. */
+    retry_after_seconds?: number;
   };
 }
 
@@ -33,9 +35,15 @@ export class TenxGraphError extends Error {
   public readonly timestamp: string;
   public readonly details: ErrorDetail[];
   public readonly context?: Record<string, any>;
-  public readonly endpoint?: string;
-  public readonly method?: string;
+  public endpoint?: string;
+  public method?: string;
   public readonly recoverySuggestion?: string;
+  /** Underlying error (fetch rejection, socket error) when there is one. */
+  public cause?: unknown;
+  /** Response headers of the failed HTTP reply, lowercased names. Absent for transport errors. */
+  public responseHeaders?: Record<string, string>;
+  /** Parsed JSON body (or raw text) of the failed HTTP reply, before any normalisation. */
+  public responseBody?: unknown;
 
   constructor(
     message: string,
@@ -148,6 +156,18 @@ export class NotFoundError extends TenxGraphError {
   }
 }
 
+/**
+ * 409 Conflict Error
+ * Thrown when the thread is busy with another run, or when a resume's
+ * `interrupt_id` does not match the open interrupt. Never retried automatically.
+ */
+export class ConflictError extends TenxGraphError {
+  constructor(message: string, requestId: string, timestamp: string, details: ErrorDetail[] = []) {
+    super(message, 409, 'CONFLICT', requestId, timestamp, details);
+    this.name = 'ConflictError';
+  }
+}
+
 /**
  * 422 Validation Error
  * Thrown when the request data fails validation
@@ -417,19 +437,248 @@ export class SerializationError extends TenxGraphError {
 }
 
 /**
- * Parse error response from API
+ * 429 Too Many Requests
+ * Carries the server's retry hint in seconds (Retry-After header, else the body's
+ * `retry_after_seconds`), or undefined when the server sent none.
  */
-export async function parseErrorResponse(response: Response): Promise<ApiErrorResponse | null> {
+export class RateLimitError extends TenxGraphError {
+  public readonly retryAfterSeconds?: number;
+
+  constructor(
+    message: string,
+    requestId: string,
+    timestamp: string,
+    details: ErrorDetail[] = [],
+    retryAfterSeconds?: number
+  ) {
+    super(
+      message,
+      429,
+      'RATE_LIMIT_EXCEEDED',
+      requestId,
+      timestamp,
+      details,
+      undefined,
+      undefined,
+      undefined,
+      'Wait for the retry-after period before sending the request again.'
+    );
+    this.name = 'RateLimitError';
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+}
+
+/**
+ * Request Timeout Error
+ * Thrown client-side when a request exceeds the configured `timeout`. statusCode is 0.
+ */
+export class RequestTimeoutError extends TenxGraphError {
+  public readonly timeoutMs: number;
+
+  constructor(timeoutMs: number, endpoint?: string, method?: string, cause?: unknown) {
+    super(
+      `Request timeout after ${timeoutMs}ms`,
+      0,
+      'REQUEST_TIMEOUT',
+      'unknown',
+      new Date().toISOString(),
+      [],
+      undefined,
+      endpoint,
+      method,
+      'Increase the client timeout or check that the server is reachable and not overloaded.'
+    );
+    this.name = 'RequestTimeoutError';
+    this.timeoutMs = timeoutMs;
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+/**
+ * Network Error
+ * Thrown when the request never got an HTTP reply (DNS failure, connection refused, offline,
+ * CORS block). `cause` holds the underlying fetch error. statusCode is 0.
+ */
+export class NetworkError extends TenxGraphError {
+  constructor(message: string, endpoint?: string, method?: string, cause?: unknown) {
+    super(
+      message,
+      0,
+      'NETWORK_ERROR',
+      'unknown',
+      new Date().toISOString(),
+      [],
+      undefined,
+      endpoint,
+      method,
+      'Check that the server is running, the base URL is correct and the network is reachable.'
+    );
+    this.name = 'NetworkError';
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+/**
+ * WebSocket Error
+ * Thrown for WebSocket failures: connection errors, unexpected close, handshake rejection.
+ * `closeCode` is the close frame code when the failure was a close.
+ */
+export class WebSocketError extends TenxGraphError {
+  public readonly closeCode?: number;
+
+  constructor(message: string, closeCode?: number, endpoint?: string, cause?: unknown) {
+    super(
+      message,
+      0,
+      'WEBSOCKET_ERROR',
+      'unknown',
+      new Date().toISOString(),
+      [],
+      undefined,
+      endpoint,
+      'WS'
+    );
+    this.name = 'WebSocketError';
+    this.closeCode = closeCode;
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+/**
+ * Stream Error
+ * Thrown when an HTTP or WebSocket run stream fails after it started: an error chunk from the
+ * server, a malformed chunk, or a stream that ended before completion.
+ */
+export class StreamError extends TenxGraphError {
+  constructor(
+    message: string,
+    errorCode: string = 'STREAM_ERROR',
+    requestId: string = 'unknown',
+    endpoint?: string,
+    method?: string,
+    cause?: unknown
+  ) {
+    super(
+      message,
+      0,
+      errorCode,
+      requestId,
+      new Date().toISOString(),
+      [],
+      undefined,
+      endpoint,
+      method
+    );
+    this.name = 'StreamError';
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+/**
+ * Normalise any JSON error body into the envelope shape. Handles the 10xGraph envelope,
+ * `{"error": "state_conflict", "detail": "..."}` (409), `{"detail": "..."}` and FastAPI's
+ * `{"detail": [{loc, msg, type}]}`. Returns null for a body that carries no usable error.
+ */
+function normalizeErrorBody(body: unknown): ApiErrorResponse | null {
+  const record = asRecord(body);
+  if (!record) return null;
+
+  const meta = asRecord(record.metadata) ?? {};
+  const metadata = {
+    message: typeof meta.message === 'string' ? meta.message : '',
+    request_id: typeof meta.request_id === 'string' ? meta.request_id : '',
+    timestamp: typeof meta.timestamp === 'string' ? meta.timestamp : '',
+  };
+
+  const err = asRecord(record.error);
+  if (err) {
+    return {
+      metadata,
+      error: {
+        code: typeof err.code === 'string' ? err.code : '',
+        message: typeof err.message === 'string' ? err.message : '',
+        details: Array.isArray(err.details) ? (err.details as ErrorDetail[]) : [],
+        ...(typeof err.retry_after_seconds === 'number'
+          ? { retry_after_seconds: err.retry_after_seconds }
+          : {}),
+      },
+    };
+  }
+
+  if (typeof record.error === 'string') {
+    const detail = typeof record.detail === 'string' ? record.detail : record.error;
+    return { metadata, error: { code: record.error, message: detail, details: [] } };
+  }
+
+  if (typeof record.detail === 'string') {
+    return { metadata, error: { code: '', message: record.detail, details: [] } };
+  }
+
+  if (Array.isArray(record.detail)) {
+    const details = record.detail.filter((d) => asRecord(d) !== null) as ErrorDetail[];
+    return {
+      metadata,
+      error: { code: '', message: details[0]?.msg || 'Validation error', details },
+    };
+  }
+
+  return null;
+}
+
+async function readErrorBody(
+  response: Response
+): Promise<{ parsed: ApiErrorResponse | null; raw: unknown }> {
   try {
-    const contentType = response.headers.get('content-type');
+    const contentType = response.headers?.get('content-type');
     if (contentType && contentType.includes('application/json')) {
-      return (await response.json()) as ApiErrorResponse;
+      const raw: unknown = await response.json();
+      return { parsed: normalizeErrorBody(raw), raw };
     }
-    return null;
+    return { parsed: null, raw: undefined };
   } catch {
     // If we can't parse the error response, return null
-    return null;
+    return { parsed: null, raw: undefined };
+  }
+}
+
+/**
+ * Parse error response from API
+ */
+export async function parseErrorResponse(response: Response): Promise<ApiErrorResponse | null> {
+  return (await readErrorBody(response)).parsed;
+}
+
+function headersToRecord(response: Response): Record<string, string> {
+  const out: Record<string, string> = {};
+  try {
+    response.headers?.forEach((value, name) => {
+      out[name.toLowerCase()] = value;
+    });
+  } catch {
+    // ignore unreadable headers
   }
+  return out;
+}
+
+/** Parse a Retry-After header (delta-seconds or HTTP date) into whole seconds. */
+function parseRetryAfter(value: string | null | undefined): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds;
+  const date = Date.parse(value);
+  if (!Number.isNaN(date)) return Math.max(0, Math.ceil((date - Date.now()) / 1000));
+  return undefined;
+}
+
+function codeMatches(code: string, prefixes: string[]): boolean {
+  const upper = code.toUpperCase();
+  return prefixes.some((prefix) => upper.startsWith(prefix));
 }
 
 /**
@@ -441,113 +690,103 @@ export async function createErrorFromResponse(
   endpoint?: string,
   method?: string
 ): Promise<TenxGraphError> {
-  const errorData = await parseErrorResponse(response);
-
-  // If we successfully parsed the error response
-  if (errorData) {
-    const { metadata, error } = errorData;
-    const message = error.message || fallbackMessage || `HTTP error ${response.status}`;
-    const requestId = metadata.request_id || 'unknown';
-    const timestamp = metadata.timestamp || new Date().toISOString();
-    const details = error.details || [];
-    const errorCode = error.code || '';
-
-    // Try to match specific error types by error code first (takes priority)
-    if (errorCode.startsWith('GRAPH_RECURSION')) {
-      return new GraphRecursionError(message, requestId, timestamp, details);
-    } else if (errorCode.startsWith('GRAPH')) {
-      return new GraphError(message, requestId, timestamp, details);
-    } else if (errorCode.startsWith('NODE')) {
-      return new NodeError(message, requestId, timestamp, details);
-    } else if (errorCode.startsWith('TRANSIENT_STORAGE')) {
-      return new TransientStorageError(message, requestId, timestamp, details);
-    } else if (errorCode.startsWith('STORAGE')) {
-      return new StorageError(message, requestId, timestamp, details);
-    } else if (errorCode.startsWith('METRICS')) {
-      return new MetricsError(message, requestId, timestamp, details);
-    } else if (errorCode.startsWith('SCHEMA_VERSION')) {
-      return new SchemaVersionError(message, requestId, timestamp, details);
-    } else if (errorCode.startsWith('SERIALIZATION')) {
-      return new SerializationError(message, requestId, timestamp, details);
-    }
+  const { parsed: errorData, raw } = await readErrorBody(response);
+  const headerRequestId = response.headers?.get('x-request-id') || '';
 
-    // Match by HTTP status code
-    switch (response.status) {
-      case 400:
-        return new BadRequestError(message, requestId, timestamp, details);
-      case 401:
-        return new AuthenticationError(message, requestId, timestamp, details);
-      case 403:
-        return new PermissionError(message, requestId, timestamp, details);
-      case 404:
-        return new NotFoundError(message, requestId, timestamp, details);
-      case 422:
-        return new ValidationError(message, requestId, timestamp, details);
-      case 500:
-      case 502:
-      case 503:
-      case 504:
-        return new ServerError(
-          message,
-          requestId,
-          timestamp,
-          errorCode || 'INTERNAL_SERVER_ERROR',
-          details,
-          response.status
-        );
-      default:
-        return new TenxGraphError(
-          message,
-          response.status,
-          errorCode || 'UNKNOWN_ERROR',
-          requestId,
-          timestamp,
-          details,
-          undefined,
-          endpoint,
-          method
-        );
-    }
+  const message =
+    errorData?.error.message || fallbackMessage || `HTTP error! status: ${response.status}`;
+  const requestId = errorData?.metadata.request_id || headerRequestId || 'unknown';
+  const timestamp = errorData?.metadata.timestamp || new Date().toISOString();
+  const details = errorData?.error.details || [];
+  const errorCode = errorData?.error.code || '';
+
+  const error = buildError(response.status, errorCode, message, requestId, timestamp, details, {
+    retryAfter:
+      parseRetryAfter(response.headers?.get('retry-after')) ?? errorData?.error.retry_after_seconds,
+    endpoint,
+    method,
+  });
+  error.endpoint = endpoint;
+  error.method = method;
+  error.responseHeaders = headersToRecord(response);
+  if (raw !== undefined) error.responseBody = raw;
+  return error;
+}
+
+function buildError(
+  status: number,
+  errorCode: string,
+  message: string,
+  requestId: string,
+  timestamp: string,
+  details: ErrorDetail[],
+  extra: { retryAfter?: number; endpoint?: string; method?: string }
+): TenxGraphError {
+  // Core error codes first (they take priority over the HTTP status). The server sends
+  // RECURSION_001, STORAGE_TRANSIENT_000, STORAGE_SCHEMA_000 and STORAGE_SERIALIZATION_000;
+  // the older GRAPH_RECURSION / TRANSIENT_STORAGE / SCHEMA_VERSION / SERIALIZATION spellings
+  // are still accepted. Specific storage codes must be tested before the STORAGE prefix.
+  if (codeMatches(errorCode, ['RECURSION', 'GRAPH_RECURSION'])) {
+    return new GraphRecursionError(message, requestId, timestamp, details);
+  } else if (codeMatches(errorCode, ['GRAPH'])) {
+    return new GraphError(message, requestId, timestamp, details);
+  } else if (codeMatches(errorCode, ['NODE'])) {
+    return new NodeError(message, requestId, timestamp, details);
+  } else if (codeMatches(errorCode, ['STORAGE_TRANSIENT', 'TRANSIENT_STORAGE'])) {
+    return new TransientStorageError(message, requestId, timestamp, details);
+  } else if (codeMatches(errorCode, ['STORAGE_SCHEMA', 'SCHEMA_VERSION'])) {
+    return new SchemaVersionError(message, requestId, timestamp, details);
+  } else if (codeMatches(errorCode, ['STORAGE_SERIALIZATION', 'SERIALIZATION'])) {
+    return new SerializationError(message, requestId, timestamp, details);
+  } else if (codeMatches(errorCode, ['STORAGE'])) {
+    return new StorageError(message, requestId, timestamp, details);
+  } else if (codeMatches(errorCode, ['METRICS'])) {
+    return new MetricsError(message, requestId, timestamp, details);
   }
 
-  // Fallback if we couldn't parse the error response
-  const message = fallbackMessage || `HTTP error! status: ${response.status}`;
-  const timestamp = new Date().toISOString();
+  // VALIDATION_ERROR (and the older AGENTFLOW_VALIDATION_ERROR spelling) are validation errors
+  if (errorCode === 'VALIDATION_ERROR' || errorCode === 'AGENTFLOW_VALIDATION_ERROR') {
+    return new ValidationError(message, requestId, timestamp, details);
+  }
 
-  switch (response.status) {
+  switch (status) {
     case 400:
-      return new BadRequestError(message, 'unknown', timestamp);
+      return new BadRequestError(message, requestId, timestamp, details);
     case 401:
-      return new AuthenticationError(message, 'unknown', timestamp);
+      return new AuthenticationError(message, requestId, timestamp, details);
     case 403:
-      return new PermissionError(message, 'unknown', timestamp);
+      return new PermissionError(message, requestId, timestamp, details);
     case 404:
-      return new NotFoundError(message, 'unknown', timestamp);
+      return new NotFoundError(message, requestId, timestamp, details);
+    case 409:
+      return new ConflictError(message, requestId, timestamp, details);
     case 422:
-      return new ValidationError(message, 'unknown', timestamp);
+      return new ValidationError(message, requestId, timestamp, details);
+    case 429:
+      return new RateLimitError(message, requestId, timestamp, details, extra.retryAfter);
     case 500:
     case 502:
     case 503:
     case 504:
       return new ServerError(
         message,
-        'unknown',
+        requestId,
         timestamp,
-        'INTERNAL_SERVER_ERROR',
-        [],
-        response.status
+        errorCode || 'INTERNAL_SERVER_ERROR',
+        details,
+        status
       );
     default:
       return new TenxGraphError(
         message,
-        response.status,
-        'UNKNOWN_ERROR',
-        'unknown',
+        status,
+        errorCode || 'UNKNOWN_ERROR',
+        requestId,
         timestamp,
-        [],
+        details,
         undefined,
-        endpoint,
-        method
+        extra.endpoint,
+        extra.method
       );
   }
 }

package/src/index.ts

@@ -22,6 +22,8 @@ export * from './endpoints/graphTools.js';
 // Export observability Response types
 export * from './endpoints/observability.js';
 
+// Export eval report types
+
 // Export stop graph Response types
 export * from './endpoints/stopGraph.js';
 
@@ -50,6 +52,8 @@ export * from './endpoints/addThreadMessages.js';
 export * from './endpoints/threadMessage.js';
 // Export delete thread message Response types
 export * from './endpoints/deleteThreadMessage.js';
+// Export update thread message feedback types
+export * from './endpoints/updateThreadMessageFeedback.js';
 // Export delete thread Response types
 export * from './endpoints/deleteThread.js';
 // Export threads list Response types
@@ -63,6 +67,9 @@ export * from './endpoints/invoke.js';
 // Export stream types
 export * from './endpoints/stream.js';
 
+// Export interrupt payload type and approve/reject helpers
+export * from './interrupt.js';
+
 // Export WebSocket stream types
 export * from './endpoints/wsStream.js';
 
@@ -95,6 +102,8 @@ export * from './endpoints/forgetMemories.js';
 
 // Export file upload / multimodal types
 export * from './endpoints/files.js';
+// Export delete file types
+export * from './endpoints/deleteFile.js';
 
 // Export shared metadata types
 export * from './endpoints/metadata.js';

package/src/interrupt.ts

@@ -0,0 +1,60 @@
+import type { StreamChunk } from './endpoints/stream.js';
+
+/**
+ * A pause raised by `interrupt()` in a graph node or tool, waiting for a resume value.
+ * Mirrors the server payload at `chunk.data.interrupt` of an `updates` chunk whose
+ * `status` is `"interrupted"`.
+ */
+export interface Interrupt {
+  /** Unique id of this pause; echo it as `interrupt_id` when resuming. */
+  id: string;
+  /** Stable position of the call within its node or tool call. */
+  key: string;
+  /** Node that was running when the graph paused. */
+  node: string;
+  /** Payload passed to `interrupt()`: what to approve or choose from. */
+  value?: unknown;
+  /** Human-readable prompt. */
+  message?: string | null;
+  /** Machine-readable reason, for example `"tool_approval"`. */
+  reason: string;
+  /** JSON Schema the resume value must follow. */
+  response_schema?: Record<string, unknown> | null;
+  /** Tool call that paused, when `interrupt()` ran inside a tool. */
+  tool_call_id?: string | null;
+}
+
+/** Spread into the `options` of `invoke`, `stream` or `wsStream` to answer an interrupt. */
+export interface InterruptResume {
+  resume: unknown;
+  interrupt_id: string;
+}
+
+/** The pending interrupt carried by a stream chunk, or null when the chunk has none. */
+export function getInterrupt(chunk: Pick<StreamChunk, 'event' | 'data'>): Interrupt | null {
+  const data = chunk.data;
+  if (chunk.event !== 'updates' || data === null || typeof data !== 'object') return null;
+  const found = (data as { interrupt?: unknown }).interrupt;
+  if (found === null || typeof found !== 'object') return null;
+  return typeof (found as Interrupt).id === 'string' ? (found as Interrupt) : null;
+}
+
+/**
+ * Answer an interrupt with approval. `value` is what the interrupted code receives; it
+ * defaults to `true`. When the interrupt sets `response_schema`, pass a value that matches it.
+ *
+ * ```ts
+ * await client.invoke([], { config: { thread_id }, ...approveInterrupt(interrupt) });
+ * ```
+ */
+export function approveInterrupt(interrupt: Interrupt, value: unknown = true): InterruptResume {
+  return { resume: value, interrupt_id: interrupt.id };
+}
+
+/**
+ * Answer an interrupt with a cancel. The server resumes the interrupted code with `null`
+ * and does not check it against `response_schema`.
+ */
+export function rejectInterrupt(interrupt: Interrupt): InterruptResume {
+  return { resume: null, interrupt_id: interrupt.id };
+}