@taco_tsinghua/graphnode-sdk 0.1.17 → 0.1.21

package/src/http-builder.ts

@@ -0,0 +1,290 @@
+/**
+ * HTTP Request Builder (fluent)
+ * - baseUrl을 내부에 보관하고, 외부에서는 경로(path)만 넘겨 호출할 수 있게 한다.
+ * - 기본적으로 credentials: 'include' 로 세션 쿠키를 전송한다.
+ */
+
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+export interface BuilderOptions {
+  baseUrl: string; // e.g., https://api.example.com
+  fetch?: FetchLike; // Node<18 환경 등에서 주입 가능
+  defaultHeaders?: Record<string, string>;
+  credentials?: RequestCredentials; // default 'include'HttpError
+  accessToken?: string | (() => string | null);
+}
+
+// export class HttpError<TBody = unknown> extends Error {
+//   status: number;
+//   body?: TBody;
+//   constructor(message: string, status: number, body?: TBody) {
+//     super(message);
+//     this.name = 'HttpError';
+//     this.status = status;
+//     this.body = body;
+//   }
+// }
+
+export type HttpResponseSuccess<T> = {
+  isSuccess: true;
+  data: T;
+  statusCode: number;
+};
+
+export type HttpResponseError = {
+  isSuccess: false;
+  error: {
+    statusCode: number;
+    message: string;
+    body?: unknown;
+  };
+};
+
+export type HttpResponse<T> = HttpResponseSuccess<T> | HttpResponseError;
+
+export class RequestBuilder {
+  /**
+   * API 기본 URL (마지막 슬래시 제거됨)
+   * @private
+   */
+  private readonly baseUrl: string;
+
+  /**
+   * 실제 HTTP 요청을 수행할 fetch 함수 구현체
+   * @private
+   */
+  private readonly fetchImpl: FetchLike;
+
+  /**
+   * 모든 요청에 포함될 기본 HTTP 헤더 (예: Accept: application/json)
+   * @private
+   */
+  private readonly headers: Record<string, string>;
+
+  /**
+   * 자격 증명(쿠키) 전송 모드 ('include' | 'omit' | 'same-origin')
+   * - 'include'로 설정 시 브라우저가 자동으로 쿠키를 전송합니다.
+   * @private
+   */
+  private readonly credentials: RequestCredentials;
+
+  /**
+   * Access Token을 동적으로 반환하는 함수 또는 정적 문자열.
+   * - 함수로 설정된 경우 요청 시점의 최신 토큰을 조회하여 Authorization 헤더에 사용합니다.
+   * - 값이 없으면(undefined) Authorization 헤더를 추가하지 않습니다 (쿠키 인증 의존).
+   * @private
+   */
+  private readonly accessToken?: string | (() => string | null);
+
+  /**
+   * 현재 빌더가 가지고 있는 URL 경로 조각들
+   * @private
+   */
+  private readonly segments: string[];
+
+  /**
+   * 현재 빌더가 가지고 있는 쿼리 파라미터들
+   * @private
+   */
+  private readonly queryParams: URLSearchParams;
+
+  /**
+   * RequestBuilder 생성자
+   * @param opts 빌더 공통 옵션 (baseUrl, fetch, headers 등)
+   * @param segments 초기 URL 경로 조각 리스트
+   * @param query 초기 쿼리 파라미터
+   */
+  constructor(opts: BuilderOptions, segments: string[] = [], query?: URLSearchParams) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+    this.fetchImpl = opts.fetch ?? (globalThis.fetch as FetchLike);
+    this.headers = { Accept: 'application/json', ...(opts.defaultHeaders ?? {}) };
+    this.credentials = opts.credentials ?? 'include';
+    this.accessToken = opts.accessToken;
+    this.segments = segments;
+    this.queryParams = query ?? new URLSearchParams();
+  }
+
+  /**
+   * 경로 조각을 추가한다. '/v1/me' 같은 절대 경로도 허용한다.
+   * @internal SDK 내부에서만 사용된다. FE에서는 직접 호출하지 말 것.
+   */
+  path(p: string): RequestBuilder {
+    if (!p) return this;
+    if (p.startsWith('http://') || p.startsWith('https://')) {
+      // 절대 URL을 넣으면 baseUrl을 무시하고 해당 URL 전체를 하나의 세그먼트로 취급
+      return new RequestBuilder(
+        {
+          baseUrl: p,
+          fetch: this.fetchImpl,
+          defaultHeaders: this.headers,
+          credentials: this.credentials,
+          accessToken: this.accessToken,
+        },
+        [],
+        new URLSearchParams(this.queryParams)
+      );
+    }
+    const segs = p.split('/').filter(Boolean);
+    return new RequestBuilder(
+      {
+        baseUrl: this.baseUrl,
+        fetch: this.fetchImpl,
+        defaultHeaders: this.headers,
+        credentials: this.credentials,
+      },
+      [...this.segments, ...segs],
+      new URLSearchParams(this.queryParams)
+    );
+  }
+
+  /**
+   * 쿼리 파라미터를 추가한다.
+   * @internal SDK 내부에서만 사용된다. FE에서는 직접 호출하지 말 것.
+   */
+  query(params?: Record<string, unknown>): RequestBuilder {
+    if (!params) return this;
+    const q = new URLSearchParams(this.queryParams);
+    for (const [k, v] of Object.entries(params)) {
+      if (v === undefined || v === null) continue;
+      q.set(k, String(v));
+    }
+    return new RequestBuilder(
+      {
+        baseUrl: this.baseUrl,
+        fetch: this.fetchImpl,
+        defaultHeaders: this.headers,
+        credentials: this.credentials,
+      },
+      [...this.segments],
+      q
+    );
+  }
+
+  async get<T>(): Promise<HttpResponse<T>> {
+    return this.send<T>('GET');
+  }
+
+  async post<T>(body?: unknown): Promise<HttpResponse<T>> {
+    return this.send<T>('POST', body);
+  }
+
+  async patch<T>(body?: unknown): Promise<HttpResponse<T>> {
+    return this.send<T>('PATCH', body);
+  }
+
+  async delete<T>(body?: unknown): Promise<HttpResponse<T>> {
+    return this.send<T>('DELETE', body);
+  }
+
+  public url(): string {
+    const path = this.segments.length ? '/' + this.segments.map(encodeURIComponent).join('/') : '';
+    const qs = this.queryParams.toString();
+    return this.baseUrl + path + (qs ? `?${qs}` : '');
+  }
+
+  public async sendRaw(
+    method: string,
+    body?: unknown,
+    extraHeaders?: Record<string, string>
+  ): Promise<Response> {
+    const headers = { ...this.headers, ...extraHeaders } as Record<string, string>;
+
+    // Access Token 주입
+    if (this.accessToken) {
+      const token = typeof this.accessToken === 'function' ? this.accessToken() : this.accessToken;
+      if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+      }
+    }
+
+    const init: RequestInit = { method, headers, credentials: this.credentials };
+    if (body !== undefined) {
+      if (typeof FormData !== 'undefined' && body instanceof FormData) {
+        init.body = body;
+      } else {
+        headers['Content-Type'] = 'application/json';
+        init.body = JSON.stringify(body);
+      }
+    }
+
+    const makeRequest = async () => this.fetchImpl(this.url(), init);
+    let res = await makeRequest();
+
+    // 401 Unauthorized 발생 시 Refresh Token으로 갱신 시도
+    if (res.status === 401) {
+      try {
+        // Refresh API 호출 (http-builder 내부 로직 재사용 방지 위해 fetchImpl 직접 사용)
+        const refreshUrl = `${this.baseUrl}/auth/refresh`;
+        const refreshRes = await this.fetchImpl(refreshUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          credentials: 'include', // 쿠키 전송 필수
+        });
+
+        if (refreshRes.ok) {
+          // 갱신 성공 시, 원래 요청 재시도
+          // (브라우저가 새 Access Token 쿠키를 자동으로 저장했으므로, 재요청 시 새 토큰이 나감)
+          res = await makeRequest();
+        }
+      } catch (e) {
+        // Refresh 실패 시, 원래의 401 응답을 그대로 반환 (또는 로깅)
+        console.error('Auto-refresh failed:', e);
+      }
+    }
+
+    return res;
+  }
+
+  private async send<T>(method: string, body?: unknown): Promise<HttpResponse<T>> {
+    try {
+      const res = await this.sendRaw(method, body);
+      const ct = res.headers.get('content-type') || '';
+      const isJson = ct.includes('application/json') || ct.includes('application/problem+json');
+
+      const isNoContent =
+        res.status === 204 || res.status === 205 || res.headers.get('content-length') === '0';
+
+      let payload: unknown = undefined;
+
+      if (!isNoContent) {
+        if (isJson) {
+          payload = await res.json();
+        } else {
+          payload = await res.text();
+        }
+      }
+
+      if (!res.ok) {
+        return {
+          isSuccess: false,
+          error: {
+            statusCode: res.status,
+            message: `HTTP ${res.status}: ${res.statusText}`,
+            body: payload,
+          },
+        };
+      }
+      return {
+        isSuccess: true,
+        statusCode: res.status,
+        data: payload as T,
+      };
+    } catch (e) {
+      const err = e as Error;
+      return {
+        isSuccess: false,
+        error: {
+          statusCode: 0,
+          message: err.message,
+        },
+      };
+    }
+  }
+}
+
+/**
+ * 외부에서 사용: createRequestBuilder({ baseUrl }).path('/v1/me').get()
+ */
+export function createRequestBuilder(opts: BuilderOptions): RequestBuilder {
+  return new RequestBuilder(opts);
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+/**
+ * GraphNode SDK Entry Point
+ * @packageDocumentation
+ */
+
+// Barrel exports: 공개 API만 노출
+export { createGraphNodeClient, GraphNodeClient } from './client.js';
+// 내부 전송 레이어는 노출 최소화: HttpError만 공개 (RequestBuilder는 @internal)
+export type { HttpResponse } from './http-builder.js';
+
+// Endpoint classes (선택적으로 직접 사용 가능)
+export { HealthApi } from './endpoints/health.js';
+export { MeApi } from './endpoints/me.js';
+export { ConversationsApi } from './endpoints/conversations.js';
+export { GoogleAuthApi } from './endpoints/auth.google.js';
+export { GraphApi } from './endpoints/graph.js';
+export { GraphAiApi } from './endpoints/graphAi.js';
+export { NoteApi } from './endpoints/note.js';
+export { AppleAuthApi } from './endpoints/auth.apple.js';
+export { SyncApi } from './endpoints/sync.js';
+export { AiApi } from './endpoints/ai.js';
+export { NotificationApi } from './endpoints/notification.js';
+
+// Types
+export type { ProblemDetails } from './types/problem.js';
+export type { MeResponseDto, UserProfileDto } from './types/me.js';
+export type {
+  ConversationDto,
+  ConversationCreateDto,
+  ConversationUpdateDto,
+  ConversationBulkCreateDto,
+} from './types/conversation.js';
+export type { MessageDto, MessageCreateDto, MessageUpdateDto } from './types/message.js';
+export type {
+  NoteDto,
+  NoteCreateDto,
+  NoteUpdateDto,
+  FolderDto,
+  FolderCreateDto,
+  FolderUpdateDto,
+} from './types/note.js';
+export type { SyncPushRequest, SyncPullResponse } from './types/sync.js';
+export type {
+  AgentChatMode,
+  AgentChatModeHint,
+  AgentChatStreamEvent,
+  AgentChatStreamParams,
+  AgentChatStreamOptions,
+  AgentChatStreamHandler,
+} from './endpoints/agent.js';
+export { openAgentChatStream } from './endpoints/agent.js';
+export type { AIChatRequestDto, AIChatResponseDto } from './endpoints/ai.js';
+export type { GraphGenerationResponseDto } from './types/graphAi.js';
+export type {
+  AiInputData,
+  AiInputMappingNode,
+  AiInputMessage,
+  AiInputMessageAuthor,
+  AiInputMessageContent,
+} from './types/aiInput.js';

package/src/types/aiInput.ts

@@ -0,0 +1,111 @@
+/**
+ * AI 모듈 입력 데이터 DTO 정의
+ * @packageDocumentation
+ */
+
+/**
+ * 메시지 내용
+ *
+ * 메시지의 실제 콘텐츠를 담고 있습니다. 현재는 텍스트 타입만 지원합니다.
+ * @public
+ */
+export interface AiInputMessageContent {
+  /**
+   * 콘텐츠 타입 (고정값: 'text')
+   */
+  content_type: 'text';
+  /**
+   * 메시지 본문 내용의 배열. 보통 하나의 문자열 요소를 가집니다.
+   */
+  parts: string[];
+}
+
+/**
+ * 메시지 작성자 정보
+ *
+ * 메시지를 누가 작성했는지 나타냅니다.
+ * @public
+ */
+export interface AiInputMessageAuthor {
+  /**
+   * 작성자의 역할
+   * - `user`: 사용자
+   * - `assistant`: AI 모델
+   * - `system`: 시스템 프롬프트
+   */
+  role: 'user' | 'assistant' | 'system';
+}
+
+/**
+ * AI 입력 메시지 구조
+ *
+ * 개별 메시지의 상세 정보를 담는 객체입니다.
+ * @public
+ */
+export interface AiInputMessage {
+  /**
+   * 메시지 고유 ID
+   */
+  id: string;
+  /**
+   * 작성자 정보
+   */
+  author: AiInputMessageAuthor;
+  /**
+   * 메시지 내용
+   */
+  content: AiInputMessageContent;
+}
+
+/**
+ * 대화 트리 매핑 노드
+ *
+ * 대화의 흐름(트리 구조)을 표현하기 위한 노드 객체입니다.
+ * 각 노드는 메시지 정보와 부모/자식 관계를 가집니다.
+ * @public
+ */
+export interface AiInputMappingNode {
+  /**
+   * 노드 ID (메시지 ID와 동일)
+   */
+  id: string;
+  /**
+   * 해당 노드의 메시지 데이터. 루트 노드 등 일부 경우 null일 수 있음.
+   */
+  message: AiInputMessage | null;
+  /**
+   * 부모 노드의 ID. 대화의 시작점인 경우 null.
+   */
+  parent: string | null;
+  /**
+   * 자식 노드 ID들의 배열. 대화의 분기를 표현합니다.
+   */
+  children: string[];
+}
+
+/**
+ * AI 입력 데이터 (대화 스레드)
+ *
+ * 하나의 대화 스레드 전체를 나타내는 최상위 객체입니다.
+ * ChatGPT 데이터 내보내기 포맷과 호환됩니다.
+ * @public
+ */
+export interface AiInputData {
+  /**
+   * 대화 제목
+   */
+  title: string;
+  /**
+   * 생성 시간 (Unix Timestamp, 초 단위)
+   */
+  create_time: number;
+  /**
+   * 마지막 업데이트 시간 (Unix Timestamp, 초 단위)
+   */
+  update_time: number;
+  /**
+   * 메시지 노드들의 맵 (Key: 노드 ID, Value: 노드 객체)
+   * 대화의 전체 구조를 담고 있습니다.
+   */
+  mapping: Record<string, AiInputMappingNode>;
+}

package/src/types/conversation.ts

@@ -0,0 +1,51 @@
+import type { MessageDto } from './message.js';
+
+/**
+ * 대화(Conversation) DTO
+ * @public
+ * @property id 대화 ID (UUID)
+ * @property title 대화 제목
+ * @property createdAt 생성 일시 (ISO 8601)
+ * @property updatedAt 수정 일시 (ISO 8601)
+ * @property deletedAt 삭제 일시 (ISO 8601, null이면 활성)
+ * @property messages 대화에 포함된 메시지 목록
+ */
+export interface ConversationDto {
+  id: string;
+  title: string;
+  createdAt?: string; // ISO 8601
+  updatedAt?: string; // ISO 8601
+  deletedAt?: string | null; // ISO 8601
+  messages: MessageDto[];
+}
+
+/**
+ * 대화 생성 요청 DTO
+ * @public
+ * @property id 대화 ID (선택, 클라이언트 생성 시)
+ * @property title 대화 제목
+ * @property messages 초기 메시지 목록 (선택)
+ */
+export interface ConversationCreateDto {
+  id: string;
+  title: string;
+  messages?: MessageDto[];
+}
+
+/**
+ * 대화 수정 요청 DTO
+ * @public
+ * @property title 변경할 대화 제목 (선택)
+ */
+export interface ConversationUpdateDto {
+  title?: string;
+}
+
+/**
+ * 대화 일괄 생성 요청 DTO
+ * @public
+ * @property conversations 생성할 대화 목록
+ */
+export interface ConversationBulkCreateDto {
+  conversations: ConversationCreateDto[];
+}

package/src/types/graph.ts

@@ -0,0 +1,201 @@
+/**
+ * Graph API에 사용되는 타입 정의
+ */
+
+/**
+ * 그래프 노드 DTO
+ * @public
+ * @property id 노드 ID (정수)
+ * @property userId 사용자 ID
+ * @property origId 원본 데이터 ID (예: conversationId)
+ * @property clusterId 클러스터 ID
+ * @property clusterName 클러스터 이름
+ * @property timestamp 타임스탬프 (ISO 8601, null 가능)
+ * @property numMessages 메시지 수
+ * @property createdAt 생성 일시 (ISO 8601)
+ * @property updatedAt 수정 일시 (ISO 8601)
+ */
+export interface GraphNodeDto {
+  id: number;
+  userId: string;
+  origId: string;
+  clusterId: string;
+  clusterName: string;
+  timestamp: string | null;
+  numMessages: number;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * 그래프 엣지 타입 ('hard' | 'insight')
+ * @public
+ */
+export type GraphEdgeType = 'hard' | 'insight';
+
+/**
+ * 그래프 엣지 DTO
+ * @public
+ * @property userId 사용자 ID
+ * @property id 엣지 ID (선택)
+ * @property source 출발 노드 ID
+ * @property target 도착 노드 ID
+ * @property weight 가중치
+ * @property type 엣지 타입
+ * @property intraCluster 클러스터 내부 연결 여부
+ * @property createdAt 생성 일시 (ISO 8601)
+ * @property updatedAt 수정 일시 (ISO 8601)
+ */
+export interface GraphEdgeDto {
+  userId: string;
+  id?: string;
+  source: number;
+  target: number;
+  weight: number;
+  type: GraphEdgeType;
+  intraCluster: boolean;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * 그래프 클러스터 DTO
+ * @public
+ * @property id 클러스터 ID
+ * @property userId 사용자 ID
+ * @property name 클러스터 이름
+ * @property description 클러스터 설명
+ * @property size 클러스터 크기 (노드 수)
+ * @property themes 주요 테마 목록
+ * @property createdAt 생성 일시 (ISO 8601)
+ * @property updatedAt 수정 일시 (ISO 8601)
+ */
+export interface GraphClusterDto {
+  id: string;
+  userId: string;
+  name: string;
+  description: string;
+  size: number;
+  themes: string[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * 그래프 통계 DTO
+ * @public
+ * @property userId 사용자 ID
+ * @property nodes 노드 수
+ * @property edges 엣지 수
+ * @property clusters 클러스터 수
+ * @property generatedAt 생성 일시 (ISO 8601)
+ * @property metadata 추가 메타데이터
+ */
+export interface GraphStatsDto {
+  userId: string;
+  nodes: number;
+  edges: number;
+  clusters: number;
+  generatedAt?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * 그래프 서브클러스터 DTO
+ * @public
+ */
+export interface GraphSubclusterDto {
+  id: string;
+  userId: string;
+  clusterId: string;
+  nodeIds: number[];
+  representativeNodeId: number;
+  size: number;
+  density: number;
+  topKeywords: string[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * 그래프 스냅샷 DTO (전체 그래프 데이터)
+ * @public
+ * @property nodes 노드 목록
+ * @property edges 엣지 목록
+ * @property clusters 클러스터 목록
+ * @property subclusters 서브클러스터 목록
+ * @property stats 그래프 통계 (userId 제외)
+ */
+export interface GraphSnapshotDto {
+  nodes: GraphNodeDto[];
+  edges: GraphEdgeDto[];
+  clusters: GraphClusterDto[];
+  subclusters?: GraphSubclusterDto[];
+  stats: Omit<GraphStatsDto, 'userId'>;
+}
+
+/**
+ * 엣지 생성 응답 DTO
+ * @public
+ * @property id 생성된 엣지 ID
+ */
+export interface CreateEdgeResponse {
+  id: string;
+}
+
+/**
+ * 노드 업데이트 페이로드
+ * @public
+ * @property clusterId 클러스터 ID (선택)
+ * @property clusterName 클러스터 이름 (선택)
+ */
+export type UpdateNodePayload = Partial<Pick<GraphNodeDto, 'clusterId' | 'clusterName'>>;
+
+/**
+ * Graph Summary DTO
+ */
+export interface GraphSummaryDto {
+  overview: {
+    total_conversations: number;
+    time_span: string;
+    primary_interests: string[];
+    conversation_style: string;
+    most_active_period: string;
+    summary_text: string;
+  };
+  clusters: Array<{
+    cluster_id: string;
+    name: string;
+    size: number;
+    density: number;
+    centrality: number;
+    recency: string;
+    top_keywords: string[];
+    key_themes: string[];
+    common_question_types: string[];
+    insight_text: string;
+    notable_conversations: string[];
+  }>;
+  patterns: Array<{
+    pattern_type: string;
+    description: string;
+    evidence: string[];
+    significance: string;
+  }>;
+  connections: Array<{
+    source_cluster: string;
+    target_cluster: string;
+    connection_strength: number;
+    bridge_keywords: string[];
+    description: string;
+  }>;
+  recommendations: Array<{
+    type: string;
+    title: string;
+    description: string;
+    related_nodes: string[];
+    priority: string;
+  }>;
+  generated_at: string;
+  detail_level: string;
+}