@taco_tsinghua/graphnode-sdk 0.1.17 → 0.1.21

package/src/endpoints/graph.ts

@@ -0,0 +1,398 @@
+import { RequestBuilder, type HttpResponse } from '../http-builder.js';
+import type {
+  GraphNodeDto,
+  GraphEdgeDto,
+  GraphClusterDto,
+  GraphStatsDto,
+  GraphSnapshotDto,
+  GraphSubclusterDto,
+  CreateEdgeResponse,
+  UpdateNodePayload,
+} from '../types/graph.js';
+
+/**
+ * Graph API
+ *
+ * 지식 그래프(Knowledge Graph)의 노드, 엣지, 클러스터를 관리하는 API 클래스입니다.
+ * `/v1/graph` 엔드포인트 하위의 API들을 호출합니다.
+ *
+ * 주요 기능:
+ * - 노드 관리 (생성, 조회, 수정, 삭제) (`createNode`, `listNodes`, `getNode`, `updateNode`, `deleteNode`)
+ * - 엣지 관리 (생성, 조회, 삭제) (`createEdge`, `listEdges`, `deleteEdge`)
+ * - 클러스터 관리 (생성, 조회, 삭제) (`createCluster`, `listClusters`, `getCluster`, `deleteCluster`)
+ * - 그래프 통계 및 스냅샷 (`getStats`, `getSnapshot`, `saveSnapshot`)
+ *
+ * @public
+ */
+export class GraphApi {
+  private readonly rb: RequestBuilder;
+
+  constructor(rb: RequestBuilder) {
+    this.rb = rb.path('/v1/graph');
+  }
+
+  /**
+   * 새 노트를 생성하거나 기존 노드를 업데이트합니다.
+   * @param node - 생성 또는 업데이트할 노드 데이터
+   *    - `id` (number): 노드 ID (정수)
+   *    - `userId` (string): 사용자 ID
+   *    - `origId` (string): 원본 데이터 ID (예: conversationId)
+   *    - `clusterId` (string): 클러스터 ID
+   *    - `clusterName` (string): 클러스터 이름
+   *    - `timestamp` (string | null): 타임스탬프
+   *    - `numMessages` (number): 메시지 수
+   * @returns 생성 또는 업데이트된 노드 정보
+   * @example
+   * const response = await client.graph.createNode({
+   *   id: 101,
+   *   userId: 'user-123',
+   *   origId: 'conv-uuid-1',
+   *   clusterId: 'cluster-a',
+   *   clusterName: 'Project Alpha',
+   *   timestamp: new Date().toISOString(),
+   *   numMessages: 5
+   * });
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   id: 101,
+   *   userId: 'user-123',
+   *   origId: 'conv-uuid-1',
+   *   clusterId: 'cluster-a',
+   *   clusterName: 'Project Alpha',
+   *   timestamp: '...',
+   *   numMessages: 5
+   * }
+   */
+  createNode(node: GraphNodeDto): Promise<HttpResponse<GraphNodeDto>> {
+    return this.rb.path('/nodes').post<GraphNodeDto>(node);
+  }
+
+  /**
+   * 사용자의 모든 노드를 가져옵니다.
+   * @returns 노드 목록 (GraphNodeDto 배열)
+   * @example
+   * const response = await client.graph.listNodes();
+   *
+   * console.log(response.data);
+   * // Output:
+   * [
+   *   {
+   *     id: 101,
+   *     userId: 'user-123',
+   *     origId: 'conv-uuid-1',
+   *     clusterId: 'cluster-a',
+   *     clusterName: 'Project Alpha',
+   *     timestamp: '...',
+   *     numMessages: 5
+   *   },
+   *   {
+   *     id: 102,
+   *     userId: 'user-123',
+   *     origId: 'conv-uuid-2',
+   *     clusterId: 'cluster-b',
+   *     clusterName: 'Project Beta',
+   *     timestamp: '...',
+   *     numMessages: 3
+   *   }
+   * ]
+   */
+  listNodes(): Promise<HttpResponse<GraphNodeDto[]>> {
+    return this.rb.path('/nodes').get<GraphNodeDto[]>();
+  }
+
+  /**
+   * 특정 ID의 노드를 가져옵니다.
+   * @param nodeId - 가져올 노드의 ID (정수)
+   * @returns 요청한 노드 상세 정보
+   * @example
+   * const response = await client.graph.getNode(101);
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   id: 101,
+   *   userId: 'user-123',
+   *   origId: 'conv-uuid-1',
+   *   clusterId: 'cluster-a',
+   *   clusterName: 'Project Alpha',
+   *   timestamp: '...',
+   *   numMessages: 5
+   * }
+   */
+  getNode(nodeId: number): Promise<HttpResponse<GraphNodeDto>> {
+    return this.rb.path(`/nodes/${nodeId}`).get<GraphNodeDto>();
+  }
+
+  /**
+   * 특정 노드를 부분적으로 업데이트합니다.
+   * @param nodeId - 업데이트할 노드의 ID
+   * @param payload - 업데이트할 데이터
+   *    - `clusterId` (string, optional): 변경할 클러스터 ID
+   *    - `clusterName` (string, optional): 변경할 클러스터 이름
+   * @example
+   * await client.graph.updateNode(101, {
+   *   clusterName: 'Project Beta'
+   * });
+   * // Output: (No content)
+   */
+  updateNode(nodeId: number, payload: UpdateNodePayload): Promise<HttpResponse<void>> {
+    return this.rb.path(`/nodes/${nodeId}`).patch<void>(payload);
+  }
+
+  /**
+   * 특정 노드를 삭제합니다.
+   * @param nodeId - 삭제할 노드의 ID
+   * @example
+   * await client.graph.deleteNode(101);
+   * // Output: (No content)
+   */
+  deleteNode(nodeId: number): Promise<HttpResponse<void>> {
+    return this.rb.path(`/nodes/${nodeId}`).delete<void>();
+  }
+
+  /**
+   * 특정 노드와 연결된 모든 엣지를 함께 삭제합니다.
+   * @param nodeId - 삭제할 노드의 ID
+   * @example
+   * await client.graph.deleteNodeCascade(101);
+   * // Output: (No content)
+   */
+  deleteNodeCascade(nodeId: number): Promise<HttpResponse<void>> {
+    return this.rb.path(`/nodes/${nodeId}/cascade`).delete<void>();
+  }
+
+  /**
+   * 새 엣지를 생성합니다.
+   * @param edge - 생성할 엣지 데이터
+   *    - `source` (number): 출발 노드 ID
+   *    - `target` (number): 도착 노드 ID
+   *    - `weight` (number): 가중치
+   *    - `type` ('hard' | 'insight'): 엣지 타입
+   *    - `intraCluster` (boolean): 클러스터 내부 연결 여부
+   * @returns 생성된 엣지 ID
+   *    - `id` (string): 엣지 ID
+   * @example
+   * const response = await client.graph.createEdge({
+   *   source: 101,
+   *   target: 102,
+   *   weight: 0.85,
+   *   type: 'insight',
+   *   intraCluster: true
+   * });
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   id: 'edge-uuid-...'
+   * }
+   */
+  createEdge(edge: GraphEdgeDto): Promise<HttpResponse<CreateEdgeResponse>> {
+    return this.rb.path('/edges').post<CreateEdgeResponse>(edge);
+  }
+
+  /**
+   * 사용자의 모든 엣지를 가져옵니다.
+   * @returns 엣지 목록 (GraphEdgeDto 배열)
+   * @example
+   * const response = await client.graph.listEdges();
+   *
+   * console.log(response.data);
+   * // Output:
+   * [
+   *   {
+   *     id: 'edge-1',
+   *     source: 101,
+   *     target: 102,
+   *     weight: 0.85,
+   *     type: 'insight',
+   *     intraCluster: true
+   *   },
+   *   {
+   *     id: 'edge-2',
+   *     source: 102,
+   *     target: 103,
+   *     weight: 0.5,
+   *     type: 'hard',
+   *     intraCluster: false
+   *   }
+   * ]
+   */
+  listEdges(): Promise<HttpResponse<GraphEdgeDto[]>> {
+    return this.rb.path('/edges').get<GraphEdgeDto[]>();
+  }
+
+  /**
+   * 특정 엣지를 삭제합니다.
+   * @param edgeId - 삭제할 엣지의 ID
+   * @example
+   * await client.graph.deleteEdge('edge-uuid-...');
+   * // Output: (No content)
+   */
+  deleteEdge(edgeId: string): Promise<HttpResponse<void>> {
+    return this.rb.path(`/edges/${edgeId}`).delete<void>();
+  }
+
+  /**
+   * 새 클러스터를 생성하거나 기존 클러스터를 업데이트합니다.
+   * @param cluster - 생성 또는 업데이트할 클러스터 데이터
+   * @returns 생성 또는 업데이트된 클러스터
+   * @example
+   * const response = await client.graph.createCluster({
+   *   id: 'cluster-a',
+   *   name: 'Project Alpha',
+   *   summary: 'Main project discussion'
+   * });
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   id: 'cluster-a',
+   *   name: 'Project Alpha',
+   *   summary: 'Main project discussion'
+   * }
+   */
+  createCluster(cluster: GraphClusterDto): Promise<HttpResponse<GraphClusterDto>> {
+    return this.rb.path('/clusters').post<GraphClusterDto>(cluster);
+  }
+
+  /**
+   * 사용자의 모든 클러스터를 가져옵니다.
+   * @returns 클러스터 목록
+   * @example
+   * const response = await client.graph.listClusters();
+   *
+   * console.log(response.data);
+   * // Output:
+   * [
+   *   {
+   *     id: 'cluster-a',
+   *     name: 'Project Alpha',
+   *     summary: 'Main project discussion'
+   *   },
+   *   {
+   *     id: 'cluster-b',
+   *     name: 'Project Beta',
+   *     summary: 'Secondary project'
+   *   }
+   * ]
+   */
+  listClusters(): Promise<HttpResponse<GraphClusterDto[]>> {
+    return this.rb.path('/clusters').get<GraphClusterDto[]>();
+  }
+
+  /**
+   * 특정 ID의 클러스터를 가져옵니다.
+   * @param clusterId - 가져올 클러스터의 ID
+   * @returns 요청한 클러스터
+   * @example
+   * const response = await client.graph.getCluster('cluster-a');
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   id: 'cluster-a',
+   *   name: 'Project Alpha',
+   *   summary: 'Main project discussion'
+   * }
+   */
+  getCluster(clusterId: string): Promise<HttpResponse<GraphClusterDto>> {
+    return this.rb.path(`/clusters/${clusterId}`).get<GraphClusterDto>();
+  }
+
+  /**
+   * 특정 클러스터를 삭제합니다.
+   * @param clusterId - 삭제할 클러스터의 ID
+   * @example
+   * await client.graph.deleteCluster('cluster-a');
+   * // Output: (No content)
+   */
+  deleteCluster(clusterId: string): Promise<HttpResponse<void>> {
+    return this.rb.path(`/clusters/${clusterId}`).delete<void>();
+  }
+
+  // --- Subclusters ---
+
+  async listSubclusters(): Promise<HttpResponse<GraphSubclusterDto[]>> {
+    return this.rb.path('/subclusters').get<GraphSubclusterDto[]>();
+  }
+
+  async getSubcluster(subclusterId: string): Promise<HttpResponse<GraphSubclusterDto>> {
+    return this.rb.path(`/subclusters/${subclusterId}`).get<GraphSubclusterDto>();
+  }
+
+  async deleteSubcluster(subclusterId: string): Promise<HttpResponse<void>> {
+    return this.rb.path(`/subclusters/${subclusterId}`).delete<void>();
+  }
+
+  /**
+   * 특정 클러스터와 그 안의 모든 노드 및 엣지를 삭제합니다.
+   * @param clusterId - 삭제할 클러스터의 ID
+   * @example
+   * await client.graph.deleteClusterCascade('cluster-a');
+   * // Output: (No content)
+   */
+  deleteClusterCascade(clusterId: string): Promise<HttpResponse<void>> {
+    return this.rb.path(`/clusters/${clusterId}/cascade`).delete<void>();
+  }
+
+  /**
+   * 그래프 통계를 가져옵니다.
+   * @returns 그래프 통계
+   * @example
+   * const response = await client.graph.getStats();
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   nodeCount: 100,
+   *   edgeCount: 150,
+   *   clusterCount: 5,
+   *   density: 0.03
+   * }
+   */
+  getStats(): Promise<HttpResponse<GraphStatsDto>> {
+    return this.rb.path('/stats').get<GraphStatsDto>();
+  }
+
+  /**
+   * 전체 그래프 스냅샷을 가져옵니다.
+   * @returns 그래프 스냅샷
+   * @example
+   * const response = await client.graph.getSnapshot();
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   nodes: [
+   *     { id: 101, ... },
+   *     { id: 102, ... }
+   *   ],
+   *   edges: [
+   *     { id: 'edge-1', ... }
+   *   ],
+   *   clusters: [
+   *     { id: 'cluster-a', ... }
+   *   ]
+   * }
+   */
+  getSnapshot(): Promise<HttpResponse<GraphSnapshotDto>> {
+    return this.rb.path('/snapshot').get<GraphSnapshotDto>();
+  }
+
+  /**
+   * 전체 그래프 스냅샷을 서버에 저장합니다.
+   * @param snapshot - 저장할 스냅샷 데이터
+   * @example
+   * await client.graph.saveSnapshot({
+   *   nodes: [...],
+   *   edges: [...],
+   *   clusters: [...]
+   * });
+   * // Output: (No content)
+   */
+  saveSnapshot(snapshot: GraphSnapshotDto): Promise<HttpResponse<void>> {
+    return this.rb.path('/snapshot').post<void>({ snapshot });
+  }
+}

package/src/endpoints/graphAi.ts

@@ -0,0 +1,111 @@
+import { RequestBuilder, type HttpResponse } from '../http-builder.js';
+import type { GraphGenerationResponseDto } from '../types/graphAi.js';
+import type { GraphSummaryDto } from '../types/graph.js';
+import type { AiInputData } from '../types/aiInput.js';
+
+/**
+ * Graph AI API
+ *
+ * AI 기반 그래프 생성 및 분석 기능을 제공하는 API 클래스입니다.
+ * `/v1/graph-ai` 엔드포인트 하위의 API들을 호출합니다.
+ *
+ * 주요 기능:
+ * - 사용자 대화 기록 기반 그래프 생성 요청 (`generateGraph`)
+ * - [테스트용] JSON 데이터 기반 그래프 생성 요청 (`generateGraphTest`)
+ *
+ * @public
+ */
+export class GraphAiApi {
+  private readonly rb: RequestBuilder;
+
+  /**
+   * GraphAiApi 인스턴스를 생성합니다.
+   * @param rb RequestBuilder 인스턴스
+   * @internal
+   */
+  constructor(rb: RequestBuilder) {
+    this.rb = rb.path('/v1/graph-ai');
+  }
+
+  /**
+   * 현재 사용자의 대화 기록을 기반으로 그래프 생성 프로세스를 시작합니다.
+   *
+   * 이 작업은 서버에서 비동기 백그라운드 작업으로 수행됩니다.
+   * 요청이 성공하면 작업 ID(`taskId`)와 초기 상태(`queued`)를 즉시 반환합니다.
+   * 클라이언트는 이후 이 `taskId`를 사용하여 작업 상태를 조회하거나 완료 알림을 기다려야 합니다.
+   *
+   * **API Endpoint**: `POST /v1/graph-ai/generate`
+   *
+   * @returns 작업 ID와 상태를 포함한 응답 객체 (`GraphGenerationResponseDto`)
+   *
+   * @example
+   * ```typescript
+   * const response = await client.graphAi.generateGraph();
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   message: 'Graph generation started',
+   *   taskId: 'task-uuid-1234',
+   *   status: 'queued'
+   * }
+   * ```
+   */
+  async generateGraph(): Promise<HttpResponse<GraphGenerationResponseDto>> {
+    return this.rb.path('/generate').post();
+  }
+
+  /**
+   * [테스트용] 직접 JSON 데이터를 입력하여 그래프 생성을 요청합니다.
+   *
+   * DB에 저장된 대화 기록 대신, 클라이언트가 제공한 JSON 데이터를 사용하여 AI 분석을 수행합니다.
+   * 주로 개발 및 테스트 단계에서 특정 시나리오를 검증하기 위해 사용됩니다.
+   * 입력 데이터 형식은 ChatGPT의 데이터 내보내기(Export) 포맷(`AiInputData[]`)을 따릅니다.
+   *
+   * **API Endpoint**: `POST /v1/graph-ai/test/generate-json`
+   *
+   * @param data - 분석할 대화 데이터 배열 (`AiInputData[]`)
+   * @returns 작업 ID와 상태를 포함한 응답 객체 (`GraphGenerationResponseDto`)
+   *
+   * @example
+   * ```typescript
+   * const mockData = [{
+   *   title: "Test Chat",
+   *   create_time: 1234567890,
+   *   update_time: 1234567890,
+   *   mapping: { ... }
+   * }];
+   *
+   * const response = await client.graphAi.generateGraphTest(mockData);
+   * ```
+   */
+  async generateGraphTest(data: AiInputData[]): Promise<HttpResponse<GraphGenerationResponseDto>> {
+    return this.rb.path('/test/generate-json').post(data);
+  }
+
+  /**
+   * Request graph summary generation (Async)
+   *
+   * Starts a background task to generate insights and summaries for the user's graph network.
+   *
+   * **API Endpoint**: `POST /v1/graph-ai/summary`
+   *
+   * @returns Verification of task acceptance
+   */
+  async requestSummary(): Promise<HttpResponse<GraphGenerationResponseDto>> {
+    return this.rb.path('/summary').post();
+  }
+
+  /**
+   * Get generated graph summary
+   *
+   * Retrieves the previously generated summary. Returns 404 if not found or not ready.
+   *
+   * **API Endpoint**: `GET /v1/graph-ai/summary`
+   *
+   * @returns The graph summary DTO
+   */
+  async getSummary(): Promise<HttpResponse<GraphSummaryDto>> {
+    return this.rb.path('/summary').get();
+  }
+}

package/src/endpoints/health.ts

@@ -0,0 +1,40 @@
+import { RequestBuilder, type HttpResponse } from '../http-builder.js';
+
+/**
+ * 헬스 체크 응답 DTO
+ * @public
+ * @property ok 서버 상태 (true: 정상)
+ */
+export interface HealthResponse {
+  ok: boolean;
+}
+
+/**
+ * Health Check API
+ *
+ * 서버의 상태를 확인하는 API 클래스입니다.
+ * `/healthz` 엔드포인트를 호출합니다.
+ *
+ * 주요 기능:
+ * - 서버 헬스 체크 (`get`)
+ *
+ * @public
+ */
+export class HealthApi {
+  constructor(private rb: RequestBuilder) {}
+
+  /**
+   * 서버의 헬스 상태를 확인합니다.
+   * @returns 헬스 체크 결과
+   * @example
+   * const response = await client.health.get();
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   ok: true
+   * }
+   */
+  get(): Promise<HttpResponse<HealthResponse>> {
+    return this.rb.path('/healthz').get<HealthResponse>();
+  }
+}

package/src/endpoints/me.ts

@@ -0,0 +1,97 @@
+import { RequestBuilder, type HttpResponse } from '../http-builder.js';
+import type { MeResponseDto, ApiKeysResponseDto, ApiKeyModel } from '../types/me.js';
+
+/**
+ * Me API (User Profile & Settings)
+ *
+ * 현재 로그인한 사용자의 정보 및 설정을 관리하는 API 클래스입니다.
+ * `/v1/me` 및 `/auth` 관련 엔드포인트들을 호출합니다.
+ *
+ * 주요 기능:
+ * - 내 프로필 조회 (`get`)
+ * - 로그아웃 (`logout`)
+ * - API 키 관리 (조회, 업데이트, 삭제) (`getApiKeys`, `updateApiKey`, `deleteApiKey`)
+ *
+ * @public
+ */
+export class MeApi {
+  constructor(private rb: RequestBuilder) {}
+
+  /**
+   * 내 프로필 정보를 조회합니다.
+   * @returns 내 정보
+   *    - `user` (UserProfileDto): 사용자 프로필 정보
+   *      - `id` (string): 사용자 ID
+   *      - `email` (string, optional): 이메일
+   *      - `displayName` (string): 표시 이름
+   *      - `avatarUrl` (string | null): 아바타 URL
+   *      - `createdAt` (string): 생성 일시 (ISO 8601)
+   * @example
+   * const response = await client.me.get();
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   userId: '1...',
+   *   profile: {
+   *     id: '1...',
+   *     email: 'john.doe@example.com',
+   *     displayName: 'John Doe',
+   *     avatarUrl: 'https://example.com/avatar.jpg'
+   *   }
+   * }
+   */
+  get(): Promise<HttpResponse<MeResponseDto>> {
+    return this.rb.path('/v1/me').get<MeResponseDto>();
+  }
+
+  /**
+   * 로그아웃을 수행합니다.
+   * - 서버 세션을 무효화합니다.
+   * @example
+   * await client.me.logout();
+   * console.log('Logged out successfully');
+   */
+  logout(): Promise<HttpResponse<void>> {
+    // 204 No Content 예상
+    return this.rb.path('/auth/logout').post<void>();
+  }
+
+  /**
+   * 특정 모델의 API 키를 조회합니다.
+   * @param model - 조회할 API 키 모델 ('openai' | 'deepseek')
+   * @returns 마스킹된 API 키 정보
+   *    - `apiKey` (string | null): 마스킹된 API 키 (설정되지 않은 경우 null)
+   * @example
+   * const response = await client.me.getApiKeys('openai');
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   apiKey: 'sk-proj-1234...' // Masked
+   * }
+   */
+  getApiKeys(model: ApiKeyModel): Promise<HttpResponse<ApiKeysResponseDto>> {
+    return this.rb.path(`/v1/me/api-keys/${model}`).get<ApiKeysResponseDto>();
+  }
+
+  /**
+   * 특정 모델의 API 키를 설정/업데이트합니다.
+   * @param model - 설정할 API 키 모델 ('openai' | 'deepseek')
+   * @param apiKey - 설정할 API 키 값 (string)
+   * @example
+   * await client.me.updateApiKey('openai', 'sk-proj-1234567890abcdef');
+   * console.log('OpenAI API key updated');
+   */
+  updateApiKey(model: ApiKeyModel, apiKey: string): Promise<HttpResponse<void>> {
+    return this.rb.path(`/v1/me/api-keys/${model}`).patch<void>({ apiKey });
+  }
+
+  /**
+   * 특정 모델의 API 키를 삭제합니다.
+   * @example
+   * await client.me.deleteApiKey('openai');
+   * console.log('OpenAI API key deleted');
+   */
+  deleteApiKey(model: ApiKeyModel): Promise<HttpResponse<void>> {
+    return this.rb.path(`/v1/me/api-keys/${model}`).delete<void>();
+  }
+}