10xgraph-client 0.6.0 → 1.0.0-rc.2

package/src/endpoints/files.ts

@@ -3,7 +3,12 @@
  */
 
 import { createErrorFromResponse } from '../errors.js';
-import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  RequestContext,
+  fetchWithTimeout,
+} from '../request.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -86,46 +91,36 @@ export async function uploadFile(
   ctx: FileUploadContext,
   file: File | Blob | { data: Blob; filename: string }
 ): Promise<FileUploadResponse> {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), ctx.timeout);
-
-  try {
-    const formData = new FormData();
-
-    // `File` only became a global in Node 20; this package supports Node 18, where a bare
-    // `instanceof File` throws ReferenceError. Guard before touching the global.
-    if (typeof File !== 'undefined' && file instanceof File) {
-      formData.append('file', file, file.name);
-    } else if ('data' in file && 'filename' in file) {
-      formData.append('file', file.data, file.filename);
-    } else {
-      formData.append('file', file, 'upload');
-    }
-
-    const response = await fetch(`${ctx.baseUrl}/v1/files/upload`, {
-      method: 'POST',
-      headers: buildHeaders(ctx as RequestContext),
-      body: formData,
-      ...getRequestCredentials(ctx as RequestContext),
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutId);
-
-    if (!response.ok) {
-      const error = await createErrorFromResponse(
-        response,
-        'File upload failed',
-        '/v1/files/upload',
-        'POST'
-      );
-      throw error;
-    }
+  const formData = new FormData();
+
+  // `File` only became a global in Node 20; this package supports Node 18, where a bare
+  // `instanceof File` throws ReferenceError. Guard before touching the global.
+  if (typeof File !== 'undefined' && file instanceof File) {
+    formData.append('file', file, file.name);
+  } else if ('data' in file && 'filename' in file) {
+    formData.append('file', file.data, file.filename);
+  } else {
+    formData.append('file', file, 'upload');
+  }
 
-    return (await response.json()) as FileUploadResponse;
-  } finally {
-    clearTimeout(timeoutId);
+  const response = await fetchWithTimeout(ctx, `${ctx.baseUrl}/v1/files/upload`, {
+    method: 'POST',
+    headers: buildHeaders(ctx as RequestContext),
+    body: formData,
+    ...getRequestCredentials(ctx as RequestContext),
+  });
+
+  if (!response.ok) {
+    const error = await createErrorFromResponse(
+      response,
+      'File upload failed',
+      '/v1/files/upload',
+      'POST'
+    );
+    throw error;
   }
+
+  return (await response.json()) as FileUploadResponse;
 }
 
 // ---------------------------------------------------------------------------
@@ -135,33 +130,93 @@ export async function uploadFile(
  * Download a file by its file_id. Returns raw Blob.
  */
 export async function getFile(ctx: FileUploadContext, fileId: string): Promise<Blob> {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), ctx.timeout);
-
-  try {
-    const response = await fetch(`${ctx.baseUrl}/v1/files/${encodeURIComponent(fileId)}`, {
+  const response = await fetchWithTimeout(
+    ctx,
+    `${ctx.baseUrl}/v1/files/${encodeURIComponent(fileId)}`,
+    {
       method: 'GET',
       headers: buildHeaders(ctx as RequestContext),
       ...getRequestCredentials(ctx as RequestContext),
-      signal: controller.signal,
-    });
+    }
+  );
+
+  if (!response.ok) {
+    const error = await createErrorFromResponse(
+      response,
+      'File download failed',
+      `/v1/files/${fileId}`,
+      'GET'
+    );
+    throw error;
+  }
 
-    clearTimeout(timeoutId);
+  return await response.blob();
+}
 
-    if (!response.ok) {
-      const error = await createErrorFromResponse(
-        response,
-        'File download failed',
-        `/v1/files/${fileId}`,
-        'GET'
-      );
-      throw error;
-    }
+// ---------------------------------------------------------------------------
+// List files (GET /v1/files)
+// ---------------------------------------------------------------------------
+export interface ListFilesRequest {
+  /** Page size (server default 50, maximum 200). */
+  limit?: number;
+  /** Number of files to skip. */
+  offset?: number;
+}
+
+export interface FileListItem {
+  file_id: string;
+  filename: string | null;
+  mime_type: string;
+  size_bytes: number;
+  url: string;
+  /** Unix seconds, or null when the store records no timestamp. */
+  created_at: number | null;
+}
+
+export interface ListFilesResponse {
+  data: {
+    files: FileListItem[];
+    has_more: boolean;
+    offset: number;
+    limit: number;
+  };
+  metadata?: {
+    request_id: string;
+    timestamp: string;
+    message: string;
+  };
+}
 
-    return await response.blob();
-  } finally {
-    clearTimeout(timeoutId);
+/**
+ * List the caller's uploaded files. A store that cannot enumerate its files
+ * (for example a cloud store) answers 501, which is thrown as a TenxGraphError.
+ */
+export async function listFiles(
+  ctx: FileUploadContext,
+  params?: ListFilesRequest
+): Promise<ListFilesResponse> {
+  const query = new URLSearchParams();
+  if (params?.limit !== undefined) query.append('limit', String(params.limit));
+  if (params?.offset !== undefined) query.append('offset', String(params.offset));
+  const qs = query.toString();
+
+  const response = await fetchWithTimeout(ctx, `${ctx.baseUrl}/v1/files${qs ? `?${qs}` : ''}`, {
+    method: 'GET',
+    headers: buildHeaders(ctx as RequestContext),
+    ...getRequestCredentials(ctx as RequestContext),
+  });
+
+  if (!response.ok) {
+    const error = await createErrorFromResponse(
+      response,
+      'List files request failed',
+      '/v1/files',
+      'GET'
+    );
+    throw error;
   }
+
+  return (await response.json()) as ListFilesResponse;
 }
 
 // ---------------------------------------------------------------------------
@@ -171,33 +226,27 @@ export async function getFileInfo(
   ctx: FileUploadContext,
   fileId: string
 ): Promise<FileInfoResponse> {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), ctx.timeout);
-
-  try {
-    const response = await fetch(`${ctx.baseUrl}/v1/files/${encodeURIComponent(fileId)}/info`, {
+  const response = await fetchWithTimeout(
+    ctx,
+    `${ctx.baseUrl}/v1/files/${encodeURIComponent(fileId)}/info`,
+    {
       method: 'GET',
       headers: buildHeaders(ctx as RequestContext),
       ...getRequestCredentials(ctx as RequestContext),
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutId);
-
-    if (!response.ok) {
-      const error = await createErrorFromResponse(
-        response,
-        'File info request failed',
-        `/v1/files/${fileId}/info`,
-        'GET'
-      );
-      throw error;
     }
-
-    return (await response.json()) as FileInfoResponse;
-  } finally {
-    clearTimeout(timeoutId);
+  );
+
+  if (!response.ok) {
+    const error = await createErrorFromResponse(
+      response,
+      'File info request failed',
+      `/v1/files/${fileId}/info`,
+      'GET'
+    );
+    throw error;
   }
+
+  return (await response.json()) as FileInfoResponse;
 }
 
 // ---------------------------------------------------------------------------
@@ -207,33 +256,27 @@ export async function getFileAccessUrl(
   ctx: FileUploadContext,
   fileId: string
 ): Promise<FileAccessUrlResponse> {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), ctx.timeout);
-
-  try {
-    const response = await fetch(`${ctx.baseUrl}/v1/files/${encodeURIComponent(fileId)}/url`, {
+  const response = await fetchWithTimeout(
+    ctx,
+    `${ctx.baseUrl}/v1/files/${encodeURIComponent(fileId)}/url`,
+    {
       method: 'GET',
       headers: buildHeaders(ctx as RequestContext),
       ...getRequestCredentials(ctx as RequestContext),
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutId);
-
-    if (!response.ok) {
-      const error = await createErrorFromResponse(
-        response,
-        'File access URL request failed',
-        `/v1/files/${fileId}/url`,
-        'GET'
-      );
-      throw error;
     }
-
-    return (await response.json()) as FileAccessUrlResponse;
-  } finally {
-    clearTimeout(timeoutId);
+  );
+
+  if (!response.ok) {
+    const error = await createErrorFromResponse(
+      response,
+      'File access URL request failed',
+      `/v1/files/${fileId}/url`,
+      'GET'
+    );
+    throw error;
   }
+
+  return (await response.json()) as FileAccessUrlResponse;
 }
 
 // ---------------------------------------------------------------------------
@@ -242,33 +285,23 @@ export async function getFileAccessUrl(
 export async function getMultimodalConfig(
   ctx: FileUploadContext
 ): Promise<MultimodalConfigResponse> {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), ctx.timeout);
-
-  try {
-    const response = await fetch(`${ctx.baseUrl}/v1/config/multimodal`, {
-      method: 'GET',
-      headers: buildHeaders(ctx as RequestContext, {
-        accept: 'application/json',
-      }),
-      ...getRequestCredentials(ctx as RequestContext),
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutId);
-
-    if (!response.ok) {
-      const error = await createErrorFromResponse(
-        response,
-        'Multimodal config request failed',
-        '/v1/config/multimodal',
-        'GET'
-      );
-      throw error;
-    }
-
-    return (await response.json()) as MultimodalConfigResponse;
-  } finally {
-    clearTimeout(timeoutId);
+  const response = await fetchWithTimeout(ctx, `${ctx.baseUrl}/v1/config/multimodal`, {
+    method: 'GET',
+    headers: buildHeaders(ctx as RequestContext, {
+      accept: 'application/json',
+    }),
+    ...getRequestCredentials(ctx as RequestContext),
+  });
+
+  if (!response.ok) {
+    const error = await createErrorFromResponse(
+      response,
+      'Multimodal config request failed',
+      '/v1/config/multimodal',
+      'GET'
+    );
+    throw error;
   }
+
+  return (await response.json()) as MultimodalConfigResponse;
 }

package/src/endpoints/fixGraph.ts

@@ -1,6 +1,11 @@
 import { ResponseMetadata } from './metadata.js';
 import { createErrorFromResponse } from '../errors.js';
-import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  RequestContext,
+  fetchWithTimeout,
+} from '../request.js';
 
 export interface FixGraphContext extends RequestContext {}
 
@@ -20,10 +25,15 @@ export interface FixGraphResponse {
 }
 
 /**
- * Fix graph state by removing messages with empty tool calls
+ * Repair a thread whose run stopped after the model asked for tools but before
+ * the results were saved.
  *
- * This is useful for cleaning up incomplete tool call messages that may have
- * failed or been interrupted during execution.
+ * The server removes an assistant message when any of its tool calls has no
+ * matching tool result (matched by tool call id), then removes tool result
+ * messages whose call no longer exists. If the thread is paused (interrupt,
+ * client tool call or human approval), the unanswered calls of the latest
+ * assistant message are kept. Messages without tool calls are never touched.
+ * When nothing needs fixing, removed_count is 0 and the state is not written.
  *
  * @param context - Request context with baseUrl, auth, timeout
  * @param request - Fix request with thread_id and optional config
@@ -38,10 +48,7 @@ export async function fixGraph(
       console.debug('TenxGraphClient: Fixing graph state for thread:', request.thread_id);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
-    const response = await fetch(`${context.baseUrl}/v1/graph/fix`, {
+    const response = await fetchWithTimeout(context, `${context.baseUrl}/v1/graph/fix`, {
       method: 'POST',
       headers: buildHeaders(context as RequestContext, {
         'Content-Type': 'application/json',
@@ -49,11 +56,8 @@ export async function fixGraph(
       }),
       ...getRequestCredentials(context as RequestContext),
       body: JSON.stringify(request),
-      signal: controller.signal,
     });
 
-    clearTimeout(timeoutId);
-
     if (!response.ok) {
       console.warn(`TenxGraphClient: Fix graph failed with HTTP ${response.status}`);
       const error = await createErrorFromResponse(
@@ -80,11 +84,6 @@ export async function fixGraph(
       console.debug('TenxGraphClient: Fix graph failed:', error);
     }
 
-    if ((error as Error).name === 'AbortError') {
-      console.warn(`TenxGraphClient: Fix graph timeout after ${context.timeout}ms`);
-      throw new Error(`Request timeout after ${context.timeout}ms`);
-    }
-
     console.error('TenxGraphClient: Fix graph failed:', error);
     throw error;
   }

package/src/endpoints/forgetMemories.ts

@@ -1,6 +1,11 @@
 import { ResponseMetadata } from './metadata.js';
 import { MemoryType } from './storeMemory.js';
-import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  RequestContext,
+  fetchWithTimeout,
+} from '../request.js';
 
 export interface ForgetMemoriesContext extends RequestContext {}
 
@@ -26,70 +31,49 @@ export async function forgetMemories(
   context: ForgetMemoriesContext,
   request: ForgetMemoriesRequest
 ): Promise<ForgetMemoriesResponse> {
-  try {
-    const url = `${context.baseUrl}/v1/store/memories/forget`;
+  const url = `${context.baseUrl}/v1/store/memories/forget`;
 
-    // Prepare request body - only include optional fields if provided
-    const body: Record<string, any> = {};
+  // Prepare request body - only include optional fields if provided
+  const body: Record<string, any> = {};
 
-    if (request.config) {
-      body.config = request.config;
-    }
-    if (request.options) {
-      body.options = request.options;
-    }
-    if (request.memory_type) {
-      body.memory_type = request.memory_type;
-    }
-    if (request.category) {
-      body.category = request.category;
-    }
-    if (request.filters) {
-      body.filters = request.filters;
-    }
-
-    if (context.debug) {
-      console.log('[DEBUG] Forget memories request:', body);
-    }
-
-    const controller = new AbortController();
-    // `ReturnType<typeof setTimeout>` rather than NodeJS.Timeout: this client runs in
-    // browsers too, and the NodeJS namespace would force consumers to install @types/node.
-    let timeoutId: ReturnType<typeof setTimeout> | undefined;
-
-    if (context.timeout > 0) {
-      timeoutId = setTimeout(() => controller.abort(), context.timeout);
-    }
-
-    const response = await fetch(url, {
-      method: 'POST',
-      headers: buildHeaders(context as RequestContext, {
-        'Content-Type': 'application/json',
-      }),
-      ...getRequestCredentials(context as RequestContext),
-      body: JSON.stringify(body),
-      ...(context.timeout > 0 && { signal: controller.signal }),
-    });
-
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-    }
+  if (request.config) {
+    body.config = request.config;
+  }
+  if (request.options) {
+    body.options = request.options;
+  }
+  if (request.memory_type) {
+    body.memory_type = request.memory_type;
+  }
+  if (request.category) {
+    body.category = request.category;
+  }
+  if (request.filters) {
+    body.filters = request.filters;
+  }
 
-    if (!response.ok) {
-      throw new Error(`Forget memories failed: ${response.status} ${response.statusText}`);
-    }
+  if (context.debug) {
+    console.log('[DEBUG] Forget memories request:', body);
+  }
 
-    const data: ForgetMemoriesResponse = await response.json();
+  const response = await fetchWithTimeout(context, url, {
+    method: 'POST',
+    headers: buildHeaders(context as RequestContext, {
+      'Content-Type': 'application/json',
+    }),
+    ...getRequestCredentials(context as RequestContext),
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Forget memories failed: ${response.status} ${response.statusText}`);
+  }
 
-    if (context.debug) {
-      console.log('[DEBUG] Forget memories response:', data);
-    }
+  const data: ForgetMemoriesResponse = await response.json();
 
-    return data;
-  } catch (error) {
-    if ((error as Error).name === 'AbortError') {
-      throw error;
-    }
-    throw error;
+  if (context.debug) {
+    console.log('[DEBUG] Forget memories response:', data);
   }
+
+  return data;
 }

package/src/endpoints/getMemory.ts

@@ -1,6 +1,12 @@
 import { ResponseMetadata } from './metadata.js';
 import { createErrorFromResponse } from '../errors.js';
-import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  RequestContext,
+  fetchWithTimeout,
+  encodePathSegment,
+} from '../request.js';
 import { MemoryResult } from './searchMemory.js';
 
 export interface GetMemoryContext extends RequestContext {}
@@ -29,10 +35,7 @@ export async function getMemory(
       console.debug('TenxGraphClient: Fetching memory with ID:', request.memoryId);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
-    const url = `${context.baseUrl}/v1/store/memories/${request.memoryId}`;
+    const url = `${context.baseUrl}/v1/store/memories/${encodePathSegment(request.memoryId)}`;
 
     // Prepare request body
     const body = {
@@ -40,18 +43,15 @@ export async function getMemory(
       options: request.options || {},
     };
 
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(context, url, {
       method: 'POST',
       headers: buildHeaders(context as RequestContext, {
         'Content-Type': 'application/json',
       }),
       ...getRequestCredentials(context as RequestContext),
       body: JSON.stringify(body),
-      signal: controller.signal,
     });
 
-    clearTimeout(timeoutId);
-
     if (!response.ok) {
       console.warn(`TenxGraphClient: Get memory failed with HTTP ${response.status}`);
       const error = await createErrorFromResponse(

package/src/endpoints/graph.ts

@@ -1,6 +1,11 @@
 import { ResponseMetadata } from './metadata.js';
 import { createErrorFromResponse } from '../errors.js';
-import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import {
+  buildHeaders,
+  getRequestCredentials,
+  RequestContext,
+  fetchWithTimeout,
+} from '../request.js';
 
 export interface GraphContext extends RequestContext {}
 
@@ -15,20 +20,33 @@ export interface GraphEdge {
   target: string;
 }
 
+/** Live (realtime) init options the server honors. */
+export interface GraphRealtimeOptions {
+  /** Init-frame keys applied from the client (subset of voice, modalities, vad, system_prompt). */
+  client_overrides: string[];
+  /** Accepted values for the init `model`; empty means the client cannot choose. */
+  models: string[];
+  model_selectable: boolean;
+  /** The client may narrow (never widen) the agent's tool tags. */
+  tools_tags: boolean;
+}
+
 export interface GraphInfo {
   node_count: number;
   edge_count: number;
   checkpointer: boolean;
-  checkpointer_type: string;
+  checkpointer_type: string | null;
   publisher: boolean;
   store: boolean;
-  interrupt_before: string[];
-  interrupt_after: string[];
-  context_type: string;
-  id_generator: string;
-  id_type: string;
-  state_type: string;
-  state_fields: string[];
+  interrupt_before: string[] | null;
+  interrupt_after: string[] | null;
+  context_type: string | null;
+  id_generator: string | null;
+  id_type: string | null;
+  state_type: string | null;
+  state_fields: string[] | null;
+  /** Live options the server honors; null when the graph is not a realtime agent. */
+  realtime_options?: GraphRealtimeOptions | null;
 }
 
 export interface GraphData {
@@ -48,21 +66,15 @@ export async function graph(context: GraphContext): Promise<GraphResponse> {
       console.debug('TenxGraphClient: Fetching graph from', context.baseUrl);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), context.timeout);
-
-    const response = await fetch(`${context.baseUrl}/v1/graph`, {
+    const response = await fetchWithTimeout(context, `${context.baseUrl}/v1/graph`, {
       method: 'GET',
       headers: buildHeaders(context as RequestContext, {
         'Content-Type': 'application/json',
         accept: 'application/json',
       }),
       ...getRequestCredentials(context as RequestContext),
-      signal: controller.signal,
     });
 
-    clearTimeout(timeoutId);
-
     if (!response.ok) {
       console.warn(`TenxGraphClient: Graph fetch failed with HTTP ${response.status}`);
       const error = await createErrorFromResponse(
@@ -86,11 +98,6 @@ export async function graph(context: GraphContext): Promise<GraphResponse> {
       console.debug('TenxGraphClient: Graph fetch failed:', error);
     }
 
-    if ((error as Error).name === 'AbortError') {
-      console.warn(`TenxGraphClient: Graph fetch timeout after ${context.timeout}ms`);
-      throw new Error(`Request timeout after ${context.timeout}ms`);
-    }
-
     console.error('TenxGraphClient: Graph fetch failed:', error);
     throw error;
   }