10xgraph-client 0.0.0-stage → 0.6.0

package/src/endpoints/files.ts

@@ -0,0 +1,274 @@
+/**
+ * File upload and retrieval endpoints for multimodal messages.
+ */
+
+import { createErrorFromResponse } from '../errors.js';
+import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+export interface FileUploadContext extends RequestContext {}
+
+export interface FileUploadResponse {
+  data: {
+    file_id: string;
+    mime_type: string;
+    size_bytes: number;
+    filename: string;
+    extracted_text: string | null;
+    url: string;
+    direct_url?: string | null;
+    direct_url_expires_at?: number | null;
+  };
+  metadata?: {
+    request_id: string;
+    timestamp: string;
+    message: string;
+  };
+}
+
+export interface FileInfoResponse {
+  data: {
+    file_id: string;
+    mime_type: string;
+    size_bytes: number;
+    filename?: string | null;
+    extracted_text: string | null;
+    direct_url?: string | null;
+    direct_url_expires_at?: number | null;
+  };
+  metadata?: {
+    request_id: string;
+    timestamp: string;
+    message: string;
+  };
+}
+
+export interface FileAccessUrlResponse {
+  data: {
+    file_id: string;
+    url: string;
+    expires_at?: number | null;
+    mime_type: string;
+  };
+  metadata?: {
+    request_id: string;
+    timestamp: string;
+    message: string;
+  };
+}
+
+export interface MultimodalConfigResponse {
+  data: {
+    media_storage_type: string;
+    media_max_size_mb: number;
+    document_handling: string;
+  };
+  metadata?: {
+    request_id: string;
+    timestamp: string;
+    message: string;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Upload file
+// ---------------------------------------------------------------------------
+/**
+ * Upload a file (image, audio, document) to the server.
+ *
+ * @param ctx - Connection context
+ * @param file - A File, Blob, or { data: Blob; filename: string } object
+ * @returns FileUploadResponse with file_id and metadata
+ */
+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;
+    }
+
+    return (await response.json()) as FileUploadResponse;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Get file (binary download)
+// ---------------------------------------------------------------------------
+/**
+ * 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)}`, {
+      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 download failed',
+        `/v1/files/${fileId}`,
+        'GET'
+      );
+      throw error;
+    }
+
+    return await response.blob();
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Get file info (metadata)
+// ---------------------------------------------------------------------------
+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`, {
+      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);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Get file access URL
+// ---------------------------------------------------------------------------
+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`, {
+      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);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Get multimodal config
+// ---------------------------------------------------------------------------
+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);
+  }
+}

package/src/endpoints/fixGraph.ts

@@ -0,0 +1,91 @@
+import { ResponseMetadata } from './metadata.js';
+import { createErrorFromResponse } from '../errors.js';
+import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+
+export interface FixGraphContext extends RequestContext {}
+
+export interface FixGraphRequest {
+  thread_id: string;
+  config?: Record<string, any>;
+}
+
+export interface FixGraphResponse {
+  data: {
+    success: boolean;
+    message: string;
+    removed_count: number;
+    state?: Record<string, any>;
+  };
+  metadata: ResponseMetadata;
+}
+
+/**
+ * Fix graph state by removing messages with empty tool calls
+ *
+ * This is useful for cleaning up incomplete tool call messages that may have
+ * failed or been interrupted during execution.
+ *
+ * @param context - Request context with baseUrl, auth, timeout
+ * @param request - Fix request with thread_id and optional config
+ * @returns Promise<FixGraphResponse> with fix operation result
+ */
+export async function fixGraph(
+  context: FixGraphContext,
+  request: FixGraphRequest
+): Promise<FixGraphResponse> {
+  try {
+    if (context.debug) {
+      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`, {
+      method: 'POST',
+      headers: buildHeaders(context as RequestContext, {
+        'Content-Type': 'application/json',
+        accept: 'application/json',
+      }),
+      ...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(
+        response,
+        'Fix graph state failed',
+        '/v1/graph/fix',
+        'POST'
+      );
+      throw error;
+    }
+
+    const data: FixGraphResponse = await response.json();
+
+    if (context.debug) {
+      console.info('TenxGraphClient: Graph state fixed successfully', {
+        removed_count: data.data.removed_count,
+        success: data.data.success,
+      });
+    }
+
+    return data;
+  } catch (error) {
+    if (context.debug) {
+      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

@@ -0,0 +1,95 @@
+import { ResponseMetadata } from './metadata.js';
+import { MemoryType } from './storeMemory.js';
+import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+
+export interface ForgetMemoriesContext extends RequestContext {}
+
+export interface ForgetMemoriesRequest {
+  config?: Record<string, any>;
+  options?: Record<string, any>;
+  memory_type?: MemoryType;
+  category?: string;
+  filters?: Record<string, any>;
+}
+
+export interface ForgetMemoriesData {
+  success: boolean;
+  data: Record<string, any>;
+}
+
+export interface ForgetMemoriesResponse {
+  data: ForgetMemoriesData;
+  metadata: ResponseMetadata;
+}
+
+export async function forgetMemories(
+  context: ForgetMemoriesContext,
+  request: ForgetMemoriesRequest
+): Promise<ForgetMemoriesResponse> {
+  try {
+    const url = `${context.baseUrl}/v1/store/memories/forget`;
+
+    // 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 (!response.ok) {
+      throw new Error(`Forget memories failed: ${response.status} ${response.statusText}`);
+    }
+
+    const data: ForgetMemoriesResponse = await response.json();
+
+    if (context.debug) {
+      console.log('[DEBUG] Forget memories response:', data);
+    }
+
+    return data;
+  } catch (error) {
+    if ((error as Error).name === 'AbortError') {
+      throw error;
+    }
+    throw error;
+  }
+}

package/src/endpoints/getMemory.ts

@@ -0,0 +1,82 @@
+import { ResponseMetadata } from './metadata.js';
+import { createErrorFromResponse } from '../errors.js';
+import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+import { MemoryResult } from './searchMemory.js';
+
+export interface GetMemoryContext extends RequestContext {}
+
+export interface GetMemoryRequest {
+  memoryId: string;
+  config?: Record<string, any>;
+  options?: Record<string, any>;
+}
+
+export interface GetMemoryData {
+  memory: MemoryResult;
+}
+
+export interface GetMemoryResponse {
+  data: GetMemoryData;
+  metadata: ResponseMetadata;
+}
+
+export async function getMemory(
+  context: GetMemoryContext,
+  request: GetMemoryRequest
+): Promise<GetMemoryResponse> {
+  try {
+    if (context.debug) {
+      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}`;
+
+    // Prepare request body
+    const body = {
+      config: request.config || {},
+      options: request.options || {},
+    };
+
+    const response = await fetch(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(
+        response,
+        'Get memory request failed',
+        '/v1/memory/{memory_id}',
+        'GET'
+      );
+      throw error;
+    }
+
+    const data: GetMemoryResponse = await response.json();
+
+    if (context.debug) {
+      console.info('TenxGraphClient: Memory fetched successfully', {
+        memory_id: request.memoryId,
+        content: data.data.memory.content.substring(0, 50),
+      });
+    }
+
+    return data;
+  } catch (error) {
+    if (context.debug) {
+      console.debug('TenxGraphClient: Get memory failed:', error);
+    }
+    throw error;
+  }
+}

package/src/endpoints/graph.ts

@@ -0,0 +1,97 @@
+import { ResponseMetadata } from './metadata.js';
+import { createErrorFromResponse } from '../errors.js';
+import { buildHeaders, getRequestCredentials, RequestContext } from '../request.js';
+
+export interface GraphContext extends RequestContext {}
+
+export interface GraphNode {
+  id: string;
+  name: string;
+}
+
+export interface GraphEdge {
+  id: string;
+  source: string;
+  target: string;
+}
+
+export interface GraphInfo {
+  node_count: number;
+  edge_count: number;
+  checkpointer: boolean;
+  checkpointer_type: string;
+  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[];
+}
+
+export interface GraphData {
+  info: GraphInfo;
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+export interface GraphResponse {
+  data: GraphData;
+  metadata: ResponseMetadata;
+}
+
+export async function graph(context: GraphContext): Promise<GraphResponse> {
+  try {
+    if (context.debug) {
+      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`, {
+      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(
+        response,
+        'Graph fetch failed',
+        '/v1/graph',
+        'GET'
+      );
+      throw error;
+    }
+
+    const data: GraphResponse = await response.json();
+
+    if (context.debug) {
+      console.info('TenxGraphClient: Graph fetch successful', data);
+    }
+
+    return data;
+  } catch (error) {
+    if (context.debug) {
+      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;
+  }
+}