@taco_tsinghua/graphnode-sdk 0.1.17 → 0.1.21

package/src/endpoints/note.ts

@@ -0,0 +1,351 @@
+import { RequestBuilder, type HttpResponse } from '../http-builder.js';
+import type {
+  NoteDto,
+  NoteCreateDto,
+  NoteUpdateDto,
+  FolderDto,
+  FolderCreateDto,
+  FolderUpdateDto,
+} from '../types/note.js';
+
+/**
+ * Note API
+ *
+ * 노트(Note)와 폴더(Folder)를 관리하는 API 클래스입니다.
+ * `/v1/notes` 및 `/v1/folders` 엔드포인트 하위의 API들을 호출합니다.
+ *
+ * 주요 기능:
+ * - 노트 관리 (생성, 조회, 수정, 삭제) (`createNote`, `listNotes`, `getNote`, `updateNote`, `deleteNote`)
+ * - 폴더 관리 (생성, 조회, 수정, 삭제) (`createFolder`, `listFolders`, `getFolder`, `updateFolder`, `deleteFolder`)
+ *
+ * @public
+ */
+export class NoteApi {
+  private readonly rb: RequestBuilder;
+
+  constructor(rb: RequestBuilder) {
+    this.rb = rb.path('/v1');
+  }
+
+  // --- Notes ---
+
+  /**
+   * 새 노트를 생성합니다.
+   * @param dto - 생성할 노트 데이터
+   *    - `id` (string): 노트 고유 ID (UUID, 클라이언트 생성)
+   *    - `content` (string): 노트 내용 (Markdown)
+   *    - `title` (string, optional): 노트 제목
+   *    - `folderId` (string | null, optional): 상위 폴더 ID (없으면 최상위)
+   * @returns 생성된 노트 정보
+   *    - `id` (string): 노트 ID
+   *    - `ownerUserId` (string): 소유자 ID
+   *    - `title` (string): 제목
+   *    - `content` (string): 내용
+   *    - `folderId` (string | null): 폴더 ID
+   *    - `createdAt` (string): 생성 일시 (ISO 8601)
+   *    - `updatedAt` (string): 수정 일시 (ISO 8601)
+   * @example
+   * const response = await client.note.createNote({
+   *   id: '550e8400-e29b-41d4-a716-446655440000',
+   *   title: 'Meeting Notes',
+   *   content: '# Weekly Sync\n- Discussed Q3 goals\n- Reviewed metrics',
+   *   folderId: null
+   * });
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   id: '550e8400-e29b-41d4-a716-446655440000',
+   *   title: 'Meeting Notes',
+   *   content: '# Weekly Sync...',
+   *   folderId: null,
+   *   createdAt: '2023-10-27T10:00:00Z',
+   *   updatedAt: '2023-10-27T10:00:00Z',
+   *   ownerUserId: 'user-123'
+   * }
+   */
+  createNote(dto: NoteCreateDto): Promise<HttpResponse<NoteDto>> {
+    return this.rb.path('/notes').post<NoteDto>(dto);
+  }
+
+  /**
+   * 사용자의 모든 노트를 가져옵니다.
+   * @returns 노트 목록 (NoteDto 배열)
+   * @example
+   * const response = await client.note.listNotes();
+   *
+   * console.log(response.data);
+   * // Output:
+   * [
+   *   {
+   *     id: '550e8400-e29b-41d4-a716-446655440000',
+   *     title: 'Meeting Notes',
+   *     content: '...',
+   *     folderId: null,
+   *     createdAt: '...',
+   *     updatedAt: '...',
+   *     ownerUserId: 'user-123'
+   *   },
+   *   {
+   *     id: '661f9511-f30c-52e5-b827-557766551111',
+   *     title: 'Ideas',
+   *     content: '...',
+   *     folderId: 'folder-123',
+   *     createdAt: '...',
+   *     updatedAt: '...',
+   *     ownerUserId: 'user-123'
+   *   }
+   * ]
+   */
+  listNotes(): Promise<HttpResponse<NoteDto[]>> {
+    return this.rb.path('/notes').get<NoteDto[]>();
+  }
+
+  /**
+   * 특정 ID의 노트를 가져옵니다.
+   * @param id - 가져올 노트의 ID (UUID)
+   * @returns 요청한 노트 상세 정보
+   * @example
+   * const response = await client.note.getNote('550e8400-e29b-41d4-a716-446655440000');
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   id: '550e8400-e29b-41d4-a716-446655440000',
+   *   title: 'Meeting Notes',
+   *   content: '# Weekly Sync\n- Discussed Q3 goals...',
+   *   folderId: null,
+   *   createdAt: '...',
+   *   updatedAt: '...',
+   *   ownerUserId: 'user-123'
+   * }
+   */
+  getNote(id: string): Promise<HttpResponse<NoteDto>> {
+    return this.rb.path(`/notes/${id}`).get<NoteDto>();
+  }
+
+  /**
+   * 특정 노드를 업데이트합니다.
+   * @param id - 업데이트할 노트의 ID
+   * @param dto - 업데이트할 데이터
+   *    - `title` (string, optional): 변경할 제목
+   *    - `content` (string, optional): 변경할 내용
+   *    - `folderId` (string | null, optional): 이동할 폴더 ID
+   * @returns 업데이트된 노트 정보
+   * @example
+   * const response = await client.note.updateNote('550e8400-e29b-41d4-a716-446655440000', {
+   *   title: 'Q3 Review Meeting',
+   *   content: '# Q3 Review\n- Goals achieved'
+   * });
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   id: '550e8400-e29b-41d4-a716-446655440000',
+   *   title: 'Q3 Review Meeting',
+   *   content: '# Q3 Review...',
+   *   folderId: null,
+   *   createdAt: '...',
+   *   updatedAt: '2023-10-27T11:30:00Z',
+   *   ownerUserId: 'user-123'
+   * }
+   */
+  updateNote(id: string, dto: NoteUpdateDto): Promise<HttpResponse<NoteDto>> {
+    return this.rb.path(`/notes/${id}`).patch<NoteDto>(dto);
+  }
+
+  /**
+   * 특정 노트를 삭제합니다.
+   * @param id - 삭제할 노트의 ID
+   * @param permanent - 영구 삭제 여부 (true: 영구 삭제, false/undefined: 휴지통 이동)
+   * @returns 성공 시 빈 응답
+   * @example
+   * // 휴지통으로 이동 (Soft Delete)
+   * const response = await client.note.deleteNote('550e8400-e29b-41d4-a716-446655440000');
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   ok: true
+   * }
+   */
+  deleteNote(id: string, permanent?: boolean): Promise<HttpResponse<void>> {
+    return this.rb.path(`/notes/${id}`).query({ permanent }).delete<void>();
+  }
+
+  /**
+   * 모든 노트를 삭제합니다.
+   * @returns 삭제된 노트 수
+   * @example
+   * const response = await client.note.deleteAllNotes();
+   * console.log(response.data.deletedCount); // 10
+   */
+  async deleteAllNotes(): Promise<HttpResponse<{ deletedCount: number }>> {
+    return this.rb.path('/notes').delete<{ deletedCount: number }>();
+  }
+
+  /**
+   * 특정 노트를 복구합니다.
+   * @param id - 복구할 노트의 ID
+   * @returns 복구된 노트 정보
+   * @example
+   * const response = await client.note.restoreNote('550e8400-e29b-41d4-a716-446655440000');
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   id: '550e8400-e29b-41d4-a716-446655440000',
+   *   title: 'Meeting Notes',
+   *   content: '...',
+   *   folderId: null,
+   *   createdAt: '...',
+   *   updatedAt: '...',
+   *   ownerUserId: 'user-123'
+   * }
+   */
+  restoreNote(id: string): Promise<HttpResponse<NoteDto>> {
+    return this.rb.path(`/notes/${id}/restore`).post<NoteDto>({});
+  }
+
+  // --- Folders ---
+
+  /**
+   * 새 폴더를 생성합니다.
+   * @param dto - 생성할 폴더 데이터
+   *    - `name` (string): 폴더 이름
+   *    - `parentId` (string | null, optional): 상위 폴더 ID (없으면 최상위)
+   * @returns 생성된 폴더 정보
+   *    - `id` (string): 폴더 ID
+   *    - `ownerUserId` (string): 소유자 ID
+   *    - `name` (string): 폴더 이름
+   *    - `parentId` (string | null): 상위 폴더 ID
+   *    - `createdAt` (string): 생성 일시
+   *    - `updatedAt` (string): 수정 일시
+   * @example
+   * const response = await client.note.createFolder({
+   *   name: 'Work Projects',
+   *   parentId: null
+   * });
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   id: 'folder-123',
+   *   name: 'Work Projects',
+   *   parentId: null,
+   *   createdAt: '...',
+   *   updatedAt: '...',
+   *   ownerUserId: 'user-123'
+   * }
+   */
+  createFolder(dto: FolderCreateDto): Promise<HttpResponse<FolderDto>> {
+    return this.rb.path('/folders').post<FolderDto>(dto);
+  }
+
+  /**
+   * 사용자의 모든 폴더를 가져옵니다.
+   * @returns 폴더 목록 (FolderDto 배열)
+   * @example
+   * const response = await client.note.listFolders();
+   *
+   * console.log(response.data);
+   * // Output:
+   * [
+   *   {
+   *     id: 'folder-123',
+   *     name: 'Work Projects',
+   *     parentId: null,
+   *     createdAt: '...',
+   *     updatedAt: '...',
+   *     ownerUserId: 'user-123'
+   *   },
+   *   {
+   *     id: 'folder-124',
+   *     name: 'Personal',
+   *     parentId: null,
+   *     createdAt: '...',
+   *     updatedAt: '...',
+   *     ownerUserId: 'user-123'
+   *   }
+   * ]
+   */
+  listFolders(): Promise<HttpResponse<FolderDto[]>> {
+    return this.rb.path('/folders').get<FolderDto[]>();
+  }
+
+  /**
+   * 특정 ID의 폴더를 가져옵니다.
+   * @param id - 가져올 폴더의 ID
+   * @returns 요청한 폴더 상세 정보
+   * @example
+   * const response = await client.note.getFolder('folder-123');
+   *
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   id: 'folder-123',
+   *   name: 'Work Projects',
+   *   parentId: null,
+   *   createdAt: '...',
+   *   updatedAt: '...',
+   *   ownerUserId: 'user-123'
+   * }
+   */
+  getFolder(id: string): Promise<HttpResponse<FolderDto>> {
+    return this.rb.path(`/folders/${id}`).get<FolderDto>();
+  }
+
+  /**
+   * 특정 폴더를 업데이트합니다.
+   * @param id - 업데이트할 폴더의 ID
+   * @param dto - 업데이트할 데이터
+   *    - `name` (string, optional): 변경할 폴더 이름
+   *    - `parentId` (string | null, optional): 이동할 상위 폴더 ID
+   * @returns 업데이트된 폴더 정보
+   * @example
+   * const response = await client.note.updateFolder('folder-123', {
+   *   name: 'Archived Projects',
+   *   parentId: 'folder-999' // Move to another folder
+   * });
+   * console.log(response.data.name); // 'Archived Projects'
+   * console.log(response.data.parentId); // 'folder-999'
+   */
+  updateFolder(id: string, dto: FolderUpdateDto): Promise<HttpResponse<FolderDto>> {
+    return this.rb.path(`/folders/${id}`).patch<FolderDto>(dto);
+  }
+
+  /**
+   * 특정 폴더를 삭제합니다.
+   * @param id - 삭제할 폴더의 ID
+   * @param permanent - 영구 삭제 여부 (true: 영구 삭제, false/undefined: 휴지통 이동)
+   * @returns 성공 시 빈 응답
+   * @example
+   * await client.note.deleteFolder('folder-123');
+   */
+  deleteFolder(id: string, permanent?: boolean): Promise<HttpResponse<void>> {
+    return this.rb.path(`/folders/${id}`).query({ permanent }).delete<void>();
+  }
+
+  /**
+   * 모든 폴더를 삭제합니다.
+   * @returns 삭제된 폴더 수
+   * @example
+   * const response = await client.note.deleteAllFolders();
+   * console.log(response.data.deletedCount); // 3
+   */
+  async deleteAllFolders(): Promise<HttpResponse<{ deletedCount: number }>> {
+    return this.rb.path('/folders').delete<{ deletedCount: number }>();
+  }
+
+  /**
+   * 특정 폴더를 복구합니다.
+   * @param id - 복구할 폴더의 ID
+   * @returns 복구된 폴더 정보
+   * @example
+   * const response = await client.note.restoreFolder('folder-123');
+   * console.log(response.data.id); // 'folder-123'
+   */
+  restoreFolder(id: string): Promise<HttpResponse<FolderDto>> {
+    return this.rb.path(`/folders/${id}/restore`).post<FolderDto>({});
+  }
+}

package/src/endpoints/notification.ts

@@ -0,0 +1,69 @@
+import { RequestBuilder } from '../http-builder.js';
+
+/**
+ * Notification API
+ *
+ * 사용자 알림 및 실시간 이벤트 스트림을 관리하는 API 클래스입니다.
+ * `/v1/notifications` 엔드포인트 하위의 API들을 사용합니다.
+ *
+ * 주요 기능:
+ * - 실시간 알림 스트림 URL 조회 (`getStreamUrl`)
+ *
+ * @public
+ */
+export class NotificationApi {
+  private readonly rb: RequestBuilder;
+
+  constructor(rb: RequestBuilder) {
+    this.rb = rb.path('/v1/notifications');
+  }
+
+  /**
+   * @deprecated
+   * 실시간 알림 수신을 위한 SSE(Server-Sent Events) 스트림 URL을 반환합니다.
+   *
+   * 이 엔드포인트는 `text/event-stream` 형식으로 데이터를 스트리밍합니다.
+   * 클라이언트는 `EventSource` API를 사용하여 연결해야 합니다.
+   *
+   * 참고:
+   * - 이 메서드는 HTTP 요청을 수행하지 않고, 연결 가능한 URL 문자열만 반환합니다.
+   * - 세션 기반 인증을 사용하므로, 브라우저의 `EventSource`가 쿠키를 전송하도록 설정해야 합니다.
+   *
+   * @returns SSE 연결을 위한 전체 URL 문자열
+   * @example
+   * const url = client.notification.getStreamUrl();
+   * const eventSource = new EventSource(url, { withCredentials: true });
+   *
+   * eventSource.onmessage = (event) => {
+   *   const data = JSON.parse(event.data);
+   *   console.log('Received notification:', data);
+   * };
+   *
+   * eventSource.onerror = (err) => {
+   *   console.error('SSE Error:', err);
+   *   eventSource.close();
+   * };
+   */
+  getStreamUrl(): string {
+    return this.rb.path('/stream').url();
+  }
+
+  /**
+   * FCM 디바이스 토큰을 등록합니다.
+   *
+   * @param token - FCM 디바이스 토큰
+   */
+  async registerDeviceToken(token: string): Promise<void> {
+    await this.rb.path('/device-token').post({ token });
+  }
+
+  /**
+   * FCM 디바이스 토큰을 삭제(등록 해제)합니다.
+   *
+   * @param token - 삭제할 FCM 디바이스 토큰
+   */
+  async removeDeviceToken(token: string): Promise<void> {
+    await this.rb.path('/device-token').delete({ token });
+  }
+
+}

package/src/endpoints/sync.ts

@@ -0,0 +1,71 @@
+import { RequestBuilder, type HttpResponse } from '../http-builder.js';
+import type { SyncPushRequest, SyncPullResponse } from '../types/sync.js';
+
+/**
+ * Sync API
+ *
+ * 클라이언트와 서버 간의 데이터 동기화를 처리하는 API 클래스입니다.
+ * `/v1/sync` 엔드포인트 하위의 API들을 호출합니다.
+ *
+ * 주요 기능:
+ * - 변경 사항 가져오기 (Pull) (`pull`)
+ * - 변경 사항 보내기 (Push) (`push`)
+ *
+ * @public
+ */
+export class SyncApi {
+  constructor(private rb: RequestBuilder) {}
+
+  /**
+   * 서버로부터 변경된 데이터를 가져옵니다 (Pull).
+   * @param since - 마지막 동기화 시각 (ISO 8601). 생략 시 모든 데이터를 가져옵니다.
+   * @returns 변경된 데이터 목록 및 서버 시각
+   *    - `conversations` (ConversationDto[]): 변경된 대화 목록
+   *    - `messages` (MessageDto[]): 변경된 메시지 목록
+   *    - `notes` (NoteDto[]): 변경된 노트 목록
+   *    - `folders` (FolderDto[]): 변경된 폴더 목록
+   *    - `serverTime` (string): 서버 현재 시각 (ISO 8601) - 다음 동기화 커서로 사용
+   * @example
+   * const lastSyncTime = '2023-10-27T10:00:00Z';
+   * const response = await client.sync.pull(lastSyncTime);
+   * console.log(response.data);
+   * // Output:
+   * {
+   *   conversations: [
+   *     { id: 'c_123', title: 'New Chat', ... }
+   *   ],
+   *   messages: [
+   *     { id: 'm_456', content: 'Hello', ... }
+   *   ],
+   *   notes: [],
+   *   folders: [],
+   *   serverTime: '2023-10-27T12:00:00Z' // Use this for next sync
+   * }
+   */
+  pull(since?: string | Date): Promise<HttpResponse<SyncPullResponse>> {
+    const sinceStr = since instanceof Date ? since.toISOString() : since;
+    return this.rb.path('/v1/sync/pull').query({ since: sinceStr }).get<SyncPullResponse>();
+  }
+
+  /**
+   * 클라이언트의 변경 사항을 서버로 전송합니다 (Push).
+   * @param data - 변경된 데이터 목록
+   *    - `conversations` (ConversationDto[], optional): 변경된 대화 목록
+   *    - `messages` (MessageDto[], optional): 변경된 메시지 목록 (conversationId 포함)
+   *    - `notes` (NoteDto[], optional): 변경된 노트 목록
+   *    - `folders` (FolderDto[], optional): 변경된 폴더 목록
+   * @example
+   * await client.sync.push({
+   *   conversations: [
+   *     { id: 'c_1', title: 'Updated Title', updatedAt: '2024-02-20T10:00:00Z' }
+   *   ],
+   *   messages: [
+   *     { id: 'm_1', conversationId: 'c_1', content: 'New message', role: 'user' }
+   *   ]
+   * });
+   * console.log('Sync push completed');
+   */
+  push(data: SyncPushRequest): Promise<HttpResponse<{ success: boolean }>> {
+    return this.rb.path('/v1/sync/push').post<{ success: boolean }>(data);
+  }
+}