@taco_tsinghua/graphnode-sdk 0.1.17 → 0.1.21

package/README.md

@@ -1,381 +1,139 @@
-# GraphNode BE SDK
+# GraphNode SDK for Frontend
 
-This SDK provides a convenient way to interact with the GraphNode Backend API from a TypeScript/JavaScript client.
+> **TACO 4기 - GraphNode 서비스 프론트엔드 연동 SDK**
 
-## Installation
+GraphNode 백엔드 API를 타입 안전(Type-Safe)하게 사용할 수 있도록 제공되는 공식 클라이언트 라이브러리입니다.
+
+## 📦 설치 (Installation)
 
 ```bash
 npm install @taco_tsinghua/graphnode-sdk
 ```
 
-## Getting Started
-
-### Initialization
-
-Create a client instance. The base URL is automatically configured to point to the GraphNode backend.
-
-```typescript
-import { createGraphNodeClient } from '@taco_tsinghua/graphnode-sdk';
-
-// No need to pass baseUrl, it defaults to the internal constant
-const client = createGraphNodeClient();
-```
-
-If you need to pass custom fetch options (e.g., for testing or specific environments):
+*(현재는 모노레포 내부 패키지로 관리되고 있습니다.)*
 
-```typescript
-const client = createGraphNodeClient({
-  // fetch: customFetch
-});
-```
-
-### API Usage Examples
-
-The client is organized by API resources.
-
-#### Health
-
-Check the health of the API server.
-
-```typescript
-const health = await client.health.check();
-console.log(health); // { ok: true }
-```
-
-#### Me (User Profile)
-
-Get the profile of the currently authenticated user.
-
-```typescript
-try {
-  const me = await client.me.getProfile();
-  console.log(me); // { id: '...', displayName: '...' }
-} catch (error) {
-  console.error('Not authenticated');
-}
-```
-
-#### Conversations
-
-**Create a single conversation:**
-
-```typescript
-const newConversation = await client.conversations.create({
-  id: 'client-generated-uuid-1',
-  title: 'My First Conversation',
-});
-console.log(newConversation);
-```
-
-**Bulk create multiple conversations:**
-
-```typescript
-const response = await client.conversations.bulkCreate({
-  conversations: [
-    { id: 'bulk-uuid-1', title: 'Bulk Conversation 1' },
-    {
-      id: 'bulk-uuid-2',
-      title: 'Bulk Conversation 2 with messages',
-      messages: [{ id: 'msg-uuid-1', role: 'user', content: 'Hello!' }],
-    },
-  ],
-});
-console.log(response.conversations); // Array of created conversations
-```
-
-**List all conversations:**
-
-```typescript
-const conversations = await client.conversations.list();
-console.log(conversations);
-```
-
-**Get a specific conversation:**
-
-```typescript
-const conversation = await client.conversations.get('conversation-id-123');
-console.log(conversation);
-```
+## 🚀 시작하기 (Getting Started)
 
-#### Messages
+### 클라이언트 초기화
 
-Create a message within a conversation:
+API 요청을 보내기 위해 `GraphNodeClient`를 초기화해야 합니다. 기본적으로 서버와의 세션(Cookie) 인증을 사용하므로 `credentials: 'include'` 옵션이 내장되어 있습니다.
 
 ```typescript
-const newMessage = await client.conversations.createMessage('conversation-id-123', {
-  id: 'message-uuid-456',
-  role: 'user',
-  content: 'Hello, this is a new message.',
-});
-console.log(newMessage);
-```
-
-#### Graph
+import { createGraphNodeClient } from 'graphnode-sdk';
 
-**Nodes:**
-
-```typescript
-// Create a node
-const node = await client.graph.createNode({
-  id: 1,
-  label: 'My Node',
-  type: 'concept',
-  properties: { color: 'red' },
+// 기본 설정으로 클라이언트 생성 (localhost:3000 기준)
+const client = createGraphNodeClient({
+  baseUrl: 'http://localhost:3000' // 배포 환경에 따라 URL 변경
 });
-
-// List nodes
-const nodes = await client.graph.listNodes();
-
-// Get node
-const myNode = await client.graph.getNode(1);
-
-// Update node
-await client.graph.updateNode(1, { label: 'Updated Node' });
-
-// Delete node
-await client.graph.deleteNode(1);
-
-// Delete node cascade (with edges)
-await client.graph.deleteNodeCascade(1);
 ```
 
-**Edges:**
+---
 
-```typescript
-// Create an edge
-const edge = await client.graph.createEdge({
-  source: 1,
-  target: 2,
-  relationship: 'related_to',
-});
+## 📚 API Reference
 
-// List edges
-const edges = await client.graph.listEdges();
+### 1. 인증 (Authentication)
 
-// Delete edge
-await client.graph.deleteEdge('edge-id');
-```
+| Method | Endpoint | Description | Status Codes |
+| :--- | :--- | :--- | :--- |
+| `client.me.getMe()` | `GET /v1/me` | 현재 로그인한 사용자 정보 조회 | `200` OK<br>`401` Unauth |
+| `client.auth.google.getStartUrl()` | - | Google 로그인 시작 URL 반환 | - |
+| `client.auth.apple.getStartUrl()` | - | Apple 로그인 시작 URL 반환 | - |
+| `client.auth.logout()` | `POST /auth/logout` | 로그아웃 (세션 쿠키 삭제) | `204` Destroyed<br>`401` Unauth |
 
-**Clusters:**
+### 2. AI 대화 (AI Chat)
 
-```typescript
-// Create cluster
-const cluster = await client.graph.createCluster({
-  name: 'My Cluster',
-  nodeIds: [1, 2],
-});
+| Method | Endpoint | Description | Status Codes |
+| :--- | :--- | :--- | :--- |
+| `client.ai.createConversation()` | `POST /v1/ai/conversations` | 새로운 대화방 생성 | `201` Created<br>`400` Bad Request |
+| `client.ai.listConversations()` | `GET /v1/ai/conversations` | 대화방 목록 조회 | `200` OK |
+| `client.ai.chat(convId, dto)` | `POST /v1/ai/conversations/:id/chat` | 메시지 전송 (파일 첨부 가능) | `200` OK<br>`400` Bad Req<br>`401` Unauth<br>`502` Upstream |
+| `openAgentChatStream()` | `POST /v1/agent/stream` | 실시간 에이전트 스트리밍 (SSE) | `200` OK (Stream) |
 
-// List clusters
-const clusters = await client.graph.listClusters();
+### 3. 그래프 AI (Graph AI)
 
-// Get cluster
-const myCluster = await client.graph.getCluster('cluster-id');
+| Method | Endpoint | Description | Status Codes |
+| :--- | :--- | :--- | :--- |
+| `client.graphAi.generateGraph()` | `POST /v1/graph-ai/generate` | 그래프 생성 요청 (Async Task) | `202` Accepted<br>`401` Unauth<br>`409` Conflict |
+| `client.graphAi.requestSummary()` | `POST /v1/graph-ai/summary` | 그래프 요약 생성 요청 (Async Task) | `202` Accepted<br>`401` Unauth<br>`409` Conflict |
+| `client.graphAi.getSummary()` | `GET /v1/graph-ai/summary` | 생성된 그래프 요약 조회 | `200` OK<br>`404` Not Found |
 
-// Delete cluster
-await client.graph.deleteCluster('cluster-id');
+### 4. 그래프 관리 (Graph Knowledge)
 
-// Delete cluster cascade
-await client.graph.deleteClusterCascade('cluster-id');
-```
+| Method | Endpoint | Description | Status Codes |
+| :--- | :--- | :--- | :--- |
+| `client.graph.listNodes()` | `GET /v1/graph/nodes` | 노드 목록 조회 | `200` OK<br>`401` Unauth |
+| `client.graph.createNode()` | `POST /v1/graph/nodes` | 노드 생성 | `201` Created<br>`400` Bad Req |
+| `client.graph.getNode(id)` | `GET /v1/graph/nodes/:id` | 노드 상세 조회 | `200` OK<br>`404` Not Found |
+| `client.graph.updateNode()` | `PATCH /v1/graph/nodes/:id` | 노드 수정 | `204` Updated<br>`404` Not Found |
+| `client.graph.deleteNode()` | `DELETE /v1/graph/nodes/:id` | 노드 삭제 | `204` Deleted<br>`401` Unauth |
+| `client.graph.createEdge()` | `POST /v1/graph/edges` | 엣지 생성 | `201` Created<br>`400` Bad Req |
+| `client.graph.getSnapshot()` | `GET /v1/graph/snapshot` | 전체 그래프 데이터 스냅샷 조회 | `200` OK<br>`401` Unauth |
 
-**Stats & Snapshot:**
+### 5. 노트 관리 (Notes & Folders)
 
-```typescript
-// Get stats
-const stats = await client.graph.getStats();
+| Method | Endpoint | Description | Status Codes |
+| :--- | :--- | :--- | :--- |
+| `client.note.createFolder()` | `POST /v1/folders` | 폴더 생성 | `201` Created<br>`400` Bad Req |
+| `client.note.createNote()` | `POST /v1/notes` | 노트 생성 | `201` Created<br>`400` Bad Req |
+| `client.note.listNotes()` | `GET /v1/notes` | 노트 목록 조회 | `200` OK<br>`401` Unauth |
+| `client.note.updateNote()` | `PATCH /v1/notes/:id` | 노트 수정 | `200` OK<br>`404` Not Found |
 
-// Get snapshot
-const snapshot = await client.graph.getSnapshot();
+### 6. 동기화 (Sync)
 
-// Save snapshot
-await client.graph.saveSnapshot(snapshot);
-```
+오프라인 우선(Offline-first) 아키텍처 지원을 위한 변경사항 동기화 API.
 
-#### Graph AI (Graph Generation)
+| Method | Endpoint | Description | Status Codes |
+| :--- | :--- | :--- | :--- |
+| `client.sync.pull()` | `GET /v1/sync/pull` | 서버 변경사항 가져오기 | `200` OK<br>`400` Bad Req |
+| `client.sync.push()` | `POST /v1/sync/push` | 클라이언트 변경사항 반영 | `200` OK<br>`400` Bad Req<br>`502` Upstream |
 
-**Generate Graph from User Conversations:**
+---
 
-Starts a background task to analyze the user's conversation history and generate a knowledge graph.
+## 💡 주요 타입 정의 (Types)
 
+### GraphSummaryDto
 ```typescript
-const response = await client.graphAi.generateGraph();
-
-if (response.isSuccess) {
-  console.log('Task Started:', response.data.taskId);
-  console.log('Status:', response.data.status);
+interface GraphSummaryDto {
+  overview: {
+    total_conversations: number;
+    summary_text: string;
+    ...
+  };
+  clusters: Array<{ name: string; insight_text: string; ... }>;
+  patterns: Array<{ pattern_type: string; description: string; ... }>;
+  connections: Array<{ source_cluster: string; target_cluster: string; ... }>;
+  recommendations: Array<{ title: string; priority: string; ... }>;
 }
 ```
 
-**Generate Graph from JSON (Test Mode):**
-
-Directly sends conversation data (in ChatGPT export format) to the AI engine for graph generation. Useful for testing without existing DB data.
-
+### SyncPushRequest
 ```typescript
-import { AiInputData } from '@taco_tsinghua/graphnode-sdk';
-
-const mockData: AiInputData[] = [
-  {
-    title: 'Test Conversation',
-    create_time: 1678900000,
-    update_time: 1678900100,
-    mapping: {
-      'msg-1': {
-        id: 'msg-1',
-        message: {
-          id: 'msg-1',
-          author: { role: 'user' },
-          content: { content_type: 'text', parts: ['Hello'] },
-        },
-        parent: null,
-        children: [],
-      },
-    },
-  },
-];
-
-const response = await client.graphAi.generateGraphTest(mockData);
-```
-
-#### Notes & Folders
-
-**Notes:**
-
-```typescript
-// Create a note
-const note = await client.note.createNote({
-  title: 'My Note',
-  content: '# Hello World',
-  folderId: null, // Optional
-});
-
-// List notes
-const notes = await client.note.listNotes();
-
-// Get note
-const myNote = await client.note.getNote('note-id');
-
-// Update note
-const updatedNote = await client.note.updateNote('note-id', {
-  content: '# Updated Content',
-});
-
-// Delete note
-await client.note.deleteNote('note-id');
+interface SyncPushRequest {
+  conversations?: ConversationDto[];
+  messages?: MessageDto[];
+  notes?: NoteDto[];
+  folders?: FolderDto[];
+}
 ```
 
-**Folders:**
+---
 
-```typescript
-// Create a folder
-const folder = await client.note.createFolder({
-  name: 'My Folder',
-  parentId: null, // Optional
-});
-
-// List folders
-const folders = await client.note.listFolders();
+## 🛠️ Error Handling
 
-// Get folder
-const myFolder = await client.note.getFolder('folder-id');
-
-// Update folder
-const updatedFolder = await client.note.updateFolder('folder-id', {
-  name: 'Updated Folder Name',
-});
-
-// Delete folder
-await client.note.deleteFolder('folder-id');
-```
-
-### Error Handling
-
-The SDK uses a unified `HttpResponse` object for all API responses, eliminating the need for `try...catch` blocks for handling HTTP errors. Each API method returns a `Promise<HttpResponse<T>>`, which is a discriminated union type. You can check the `isSuccess` property to determine if the call was successful.
+API 요청 실패 시 `HttpError`가 발생하며, 백엔드의 `ProblemDetails` 규격(`RFC 9457`)을 따릅니다.
 
 ```typescript
-import { createGraphNodeClient, HttpResponse } from '@taco_tsinghua/graphnode-sdk';
-
-const client = createGraphNodeClient();
-
-async function fetchConversation() {
-  const response = await client.conversations.get('non-existent-id');
-
-  if (response.isSuccess) {
-    // Type-safe access to `data` and `statusCode`
-    console.log('Success:', response.data);
-  } else {
-    // Type-safe access to `error`
-    console.error('API Error:', response.error.message);
-    console.error('Status:', response.error.statusCode);
-
-    // The error body might contain RFC 9457 Problem Details
-    const problem = response.error.body as { title: string; detail: string };
-    if (problem) {
-      console.error('Problem Title:', problem.title);
-      console.error('Problem Detail:', problem.detail);
-    }
+try {
+  await client.note.createNote({ ... });
+} catch (err) {
+  if (err.name === 'HttpError') {
+    // 400 Bad Request 등의 경우
+    console.error('Status:', err.response.status);
+    console.error('Problem:', err.response.data); // { type, title, detail, ... }
   }
 }
 ```
 
-### HTTP 상태 코드 가이드 (HTTP Status Codes Guide)
-
-API는 표준 HTTP 상태 코드를 사용하여 요청의 성공 또는 실패를 나타냅니다.
-
-#### 성공 코드 (General Success Codes)
-
-- **`200 OK`**: 요청이 성공적으로 처리되었습니다. 응답 본문에 요청한 데이터가 포함됩니다. (예: `GET`, `PATCH`, `PUT`)
-- **`201 Created`**: 리소스가 성공적으로 생성되었습니다. `Location` 헤더에 새 리소스의 URL이 포함되며, 본문에 생성된 리소스가 포함됩니다. (예: `POST`)
-- **`204 No Content`**: 요청은 성공했으나 반환할 본문이 없습니다. (예: `DELETE`, 본문 없는 `PATCH`)
-
-#### 에러 코드 (General Error Codes)
-
-모든 에러 응답은 **RFC 9457 Problem Details** 형식(`application/problem+json`)을 따릅니다.
-
-- **`400 Bad Request`**: 클라이언트 오류로 인해 서버가 요청을 처리할 수 없습니다(예: 잘못된 구문, 유효성 검사 실패). 응답 본문에 유효성 검사 실패에 대한 세부 정보가 포함됩니다.
-- **`401 Unauthorized`**: 요청된 응답을 받으려면 인증이 필요합니다. 세션이 유효하지 않거나 만료된 경우 발생합니다.
-- **`403 Forbidden`**: 클라이언트가 콘텐츠에 대한 접근 권한이 없습니다. 401과 달리 서버가 클라이언트의 신원을 알고 있습니다.
-- **`404 Not Found`**: 서버가 요청한 리소스를 찾을 수 없습니다.
-- **`409 Conflict`**: 요청이 서버의 현재 상태와 충돌할 때 전송됩니다(예: 이미 존재하는 리소스 생성).
-- **`429 Too Many Requests`**: 사용자가 일정 시간 동안 너무 많은 요청을 보냈습니다("속도 제한").
-- **`500 Internal Server Error`**: 서버가 처리 방법을 모르는 상황에 직면했습니다.
-- **`502 Bad Gateway`**: 업스트림 오류. 외부 서비스(예: OpenAI, DB)가 유효하지 않은 응답을 반환했습니다.
-- **`503 Service Unavailable`**: 서비스 불가. DB 연결 실패 등 일시적으로 서비스를 이용할 수 없습니다.
-- **`504 Gateway Timeout`**: 업스트림 타임아웃. 외부 서비스의 응답이 지연되어 타임아웃이 발생했습니다.
-
-#### 엔드포인트별 상태 코드 (Endpoint-Specific Status Codes)
-
-| Endpoint                               | Method   | Success Codes | Error Codes         | Description                                                                                                                                    |
-| -------------------------------------- | -------- | ------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| **/healthz**                           | `GET`    | `200`         | `503`               | API 상태를 확인합니다. <br> `503`: DB 등 필수 의존성 서비스가 다운된 경우.                                                                     |
-| **/auth/logout**                       | `POST`   | `204`         | `401`               | 사용자를 로그아웃하고 세션을 무효화합니다. <br> `401`: 이미 로그아웃되었거나 세션이 유효하지 않은 경우.                                        |
-| **/v1/me**                             | `GET`    | `200`         | `401`               | 현재 사용자의 프로필을 조회합니다. <br> `401`: 로그인하지 않은 사용자.                                                                         |
-| **/v1/me/api-keys/{model}**            | `GET`    | `200`         | `401`, `404`        | 특정 모델의 API 키를 조회합니다. <br> `401`: 미인증. <br> `404`: 해당 모델의 키가 설정되지 않음.                                               |
-|                                        | `PATCH`  | `204`         | `400`, `401`        | API 키를 업데이트합니다. <br> `400`: 키 형식이 잘못됨. <br> `401`: 미인증.                                                                     |
-|                                        | `DELETE` | `204`         | `401`               | API 키를 삭제합니다. <br> `401`: 미인증.                                                                                                       |
-| **/v1/ai/conversations**               | `POST`   | `201`         | `400`, `401`, `409` | 새 대화를 생성합니다. <br> `400`: 제목 누락 등 입력값 오류. <br> `401`: 미인증. <br> `409`: 클라이언트가 제공한 ID가 이미 존재함.              |
-|                                        | `GET`    | `200`         | `401`               | 모든 대화를 조회합니다. <br> `401`: 미인증.                                                                                                    |
-| **/v1/ai/conversations/bulk**          | `POST`   | `201`         | `400`, `401`        | 대화를 일괄 생성합니다. <br> `400`: 배열 형식이 아니거나 데이터 오류. <br> `401`: 미인증.                                                      |
-| **/v1/ai/conversations/{id}**          | `GET`    | `200`         | `401`, `404`        | 단일 대화를 조회합니다. <br> `401`: 미인증. <br> `404`: 대화를 찾을 수 없거나 삭제됨.                                                          |
-|                                        | `PATCH`  | `200`         | `400`, `401`, `404` | 대화를 업데이트합니다. <br> `400`: 입력값 오류. <br> `401`: 미인증. <br> `404`: 대화 없음.                                                     |
-|                                        | `DELETE` | `204`         | `401`, `404`        | 대화를 삭제합니다. <br> `401`: 미인증. <br> `404`: 대화 없음.                                                                                  |
-| **/v1/ai/conversations/{id}/restore**  | `POST`   | `200`         | `401`, `404`        | 삭제된 대화를 복원합니다. <br> `401`: 미인증. <br> `404`: 삭제된 대화 기록을 찾을 수 없음.                                                     |
-| **/v1/ai/conversations/{id}/messages** | `POST`   | `201`         | `400`, `401`, `404` | 대화에 메시지를 추가합니다. <br> `400`: 내용 누락 등. <br> `401`: 미인증. <br> `404`: 대화가 존재하지 않음.                                    |
-| **/v1/graph/nodes**                    | `POST`   | `201`         | `400`, `401`, `409` | 그래프 노드를 생성합니다. <br> `400`: 필수 필드 누락. <br> `401`: 미인증. <br> `409`: 노드 ID 중복.                                            |
-|                                        | `GET`    | `200`         | `401`               | 모든 그래프 노드를 조회합니다. <br> `401`: 미인증.                                                                                             |
-| **/v1/graph/nodes/{id}**               | `GET`    | `200`         | `401`, `404`        | 단일 노드를 조회합니다. <br> `401`: 미인증. <br> `404`: 노드 없음.                                                                             |
-|                                        | `PATCH`  | `204`         | `400`, `401`, `404` | 노드를 업데이트합니다. <br> `400`: 입력값 오류. <br> `401`: 미인증. <br> `404`: 노드 없음.                                                     |
-|                                        | `DELETE` | `204`         | `401`, `404`        | 노드를 삭제합니다. <br> `401`: 미인증. <br> `404`: 노드 없음.                                                                                  |
-| **/v1/graph/edges**                    | `POST`   | `201`         | `400`, `401`        | 그래프 엣지를 생성합니다. <br> `400`: Source/Target 노드 ID 오류. <br> `401`: 미인증.                                                          |
-|                                        | `GET`    | `200`         | `401`               | 모든 그래프 엣지를 조회합니다. <br> `401`: 미인증.                                                                                             |
-|                                        | `DELETE` | `204`         | `401`, `404`        | 엣지를 삭제합니다. <br> `401`: 미인증. <br> `404`: 엣지 없음.                                                                                  |
-| **/v1/notes**                          | `POST`   | `201`         | `400`, `401`        | 노트를 생성합니다. <br> `400`: 제목/내용 누락. <br> `401`: 미인증.                                                                             |
-|                                        | `GET`    | `200`         | `401`               | 모든 노트를 조회합니다. <br> `401`: 미인증.                                                                                                    |
-| **/v1/notes/{id}**                     | `GET`    | `200`         | `401`, `404`        | 단일 노트를 조회합니다. <br> `401`: 미인증. <br> `404`: 노트 없음.                                                                             |
-|                                        | `PATCH`  | `200`         | `400`, `401`, `404` | 노트를 업데이트합니다. <br> `400`: 입력값 오류. <br> `401`: 미인증. <br> `404`: 노트 없음.                                                     |
-|                                        | `DELETE` | `204`         | `401`, `404`        | 노트를 삭제합니다. <br> `401`: 미인증. <br> `404`: 노트 없음.                                                                                  |
-| **/v1/folders**                        | `POST`   | `201`         | `400`, `401`        | 폴더를 생성합니다. <br> `400`: 이름 누락. <br> `401`: 미인증.                                                                                  |
-|                                        | `GET`    | `200`         | `401`               | 모든 폴더를 조회합니다. <br> `401`: 미인증.                                                                                                    |
-| **/v1/sync/pull**                      | `GET`    | `200`         | `400`, `401`        | 변경 사항을 가져옵니다. <br> `400`: `since` 파라미터 형식 오류. <br> `401`: 미인증.                                                            |
-| **/v1/sync/push**                      | `POST`   | `204`         | `400`, `401`, `409` | 변경 사항을 푸시합니다. <br> `400`: 데이터 형식 오류. <br> `401`: 미인증. <br> `409`: 데이터 버전 충돌 (클라이언트가 구버전 데이터 수정 시도). |
-| **/v1/graph-ai/generate**              | `POST`   | `202`         | `401`, `409`        | 그래프 생성 요청을 시작합니다. <br> `401`: 미인증. <br> `409`: 이미 진행 중인 작업이 있음.                                                     |
-| **/v1/graph-ai/test/generate-json**    | `POST`   | `202`         | `400`               | [테스트용] JSON 기반 그래프 생성 요청. <br> `400`: JSON 형식이 잘못되었거나 필수 필드 누락.                                                    |
+## 📝 License
+
+This SDK is proprietary software of the TACO 4 Team.

package/dist/client.d.ts

@@ -9,6 +9,7 @@ import { NoteApi } from './endpoints/note.js';
 import { AppleAuthApi } from './endpoints/auth.apple.js';
 import { SyncApi } from './endpoints/sync.js';
 import { AiApi } from './endpoints/ai.js';
+import { NotificationApi } from './endpoints/notification.js';
 /**
  * GraphNode 클라이언트 옵션
  * @public
@@ -45,12 +46,33 @@ export declare class GraphNodeClient {
     readonly appleAuth: AppleAuthApi;
     readonly sync: SyncApi;
     readonly ai: AiApi;
+    readonly notification: NotificationApi;
+    /**
+     * HTTP 요청 빌더 인스턴스.
+     * 모든 API 엔드포인트가 이 빌더를 공유하여 HTTP 요청을 수행합니다.
+     * @private
+     */
     private readonly rb;
+    /**
+     * 현재 설정된 Access Token (Bearer 토큰).
+     * 쿠키 인증 방식을 사용할 경우 null일 수 있습니다.
+     * @private
+     */
     private _accessToken;
+    /**
+     * GraphNodeClient 생성자.
+     * - 실행 환경(브라우저/Node.js)에 맞는 fetch 함수를 자동으로 감지하여 설정합니다.
+     * - 기본 API URL 및 공통 헤더 등 통신 옵션을 초기화합니다.
+     *
+     * @param opts 클라이언트 설정 옵션
+     */
     constructor(opts?: GraphNodeClientOptions);
     /**
-     * Access Token을 설정합니다.
-     * @param token JWT Access Token 또는 null (로그아웃 시)
+     * Access Token을 동적으로 설정합니다.
+     * - 로그인 후 발급받은 토큰을 수동으로 설정하거나, 로그아웃 시 null로 초기화할 때 사용합니다.
+     * - 쿠키 기반 인증을 사용하는 경우, 이 함수를 호출하지 않아도(null 상태여도) 정상 동작합니다.
+     *
+     * @param token JWT Access Token 문자열 또는 null (초기화)
      */
     setAccessToken(token: string | null): void;
 }

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,cAAc,EAAkB,MAAM,mBAAmB,CAAC;AAE9F,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,aAAa,CAAC;IAC7F,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,aAAa,EAAE,gBAAgB,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;IACpC,OAAO,CAAC,YAAY,CAAuB;gBAE/B,IAAI,GAAE,sBAA2B;IAmC7C;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAGpC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,sBAAsB,GAAG,eAAe,CAEpF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,cAAc,EAAkB,MAAM,mBAAmB,CAAC;AAE9F,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAQ,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,aAAa,CAAC;IAC7F,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,aAAa,EAAE,gBAAgB,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;IAEvC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;IAEpC;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAAuB;IAE3C;;;;;;OAMG;gBACS,IAAI,GAAE,sBAA2B;IA8C7C;;;;;;OAMG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAGpC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,sBAAsB,GAAG,eAAe,CAEpF"}

package/dist/client.js

@@ -10,6 +10,7 @@ import { NoteApi } from './endpoints/note.js';
 import { AppleAuthApi } from './endpoints/auth.apple.js';
 import { SyncApi } from './endpoints/sync.js';
 import { AiApi } from './endpoints/ai.js';
+import { NotificationApi } from './endpoints/notification.js';
 /**
  * GraphNode API 클라이언트
  * @public
@@ -25,28 +26,49 @@ import { AiApi } from './endpoints/ai.js';
  * @property ai AI 채팅 API
  */
 export class GraphNodeClient {
+    /**
+     * GraphNodeClient 생성자.
+     * - 실행 환경(브라우저/Node.js)에 맞는 fetch 함수를 자동으로 감지하여 설정합니다.
+     * - 기본 API URL 및 공통 헤더 등 통신 옵션을 초기화합니다.
+     *
+     * @param opts 클라이언트 설정 옵션
+     */
     constructor(opts = {}) {
+        /**
+         * 현재 설정된 Access Token (Bearer 토큰).
+         * 쿠키 인증 방식을 사용할 경우 null일 수 있습니다.
+         * @private
+         */
         this._accessToken = null;
+        // 1. fetch 함수 결정 전략
+        // 사용자가 opts.fetch로 직접 주입하지 않은 경우, 환경에 따라 적절한 기본 fetch를 찾습니다.
         let fetchFn = opts.fetch;
         if (!fetchFn) {
             if (typeof window !== 'undefined' && window.fetch) {
-                // 1. 브라우저 / Electron Renderer 환경
-                // window.fetch를 그냥 넘기면 'Illegal invocation' 발생하므로 bind 처리
+                // [Browser / Electron Renderer 환경]
+                // window.fetch는 호출 시 'this'가 window여야 하므로 bind(window)가 필수입니다.
+                // 그냥 할당하면 "Illegal invocation" 에러가 발생할 수 있습니다.
                 fetchFn = window.fetch.bind(window);
             }
             else if (typeof globalThis !== 'undefined' && globalThis.fetch) {
-                // 2. Node.js (v18+) / 기타 환경
+                // [Node.js 18+ / Bun / Deno 등 환경]
+                // 전역 스코프(globalThis)에 있는 fetch를 사용합니다.
                 fetchFn = globalThis.fetch.bind(globalThis);
             }
         }
         this._accessToken = opts.accessToken ?? null;
-        // 내부 고정 baseUrl 사용, FE는 fetch/headers/credentials 정도만 선택 주입 가능
+        // 2. RequestBuilder 초기화
+        // createRequestBuilder를 통해 내부적으로 사용할 HTTP 요청 처리기를 만듭니다.
+        // 여기서 accessToken을 '함수' 형태로 넘기는 이유는,
+        // 나중에 setAccessToken()으로 값이 바뀌었을 때, RequestBuilder가 최신 값을 참조할 수 있게 하기 위함입니다.
         this.rb = createRequestBuilder({
             baseUrl: GRAPHNODE_BASE_URL,
             ...opts,
-            fetch: fetchFn, // 바인딩된 fetch 주입
-            accessToken: () => this._accessToken, // 동적 토큰 주입을 위한 함수 전달
+            fetch: fetchFn, // 결정된 fetch 함수 주입
+            accessToken: () => this._accessToken, // [중요] 동적 토큰 참조를 위한 Getter 함수 전달
         });
+        // 3. 각 API 모듈 초기화
+        // 각 모듈은 공유된 RequestBuilder(this.rb)를 사용하여 통신합니다.
         this.health = new HealthApi(this.rb);
         this.me = new MeApi(this.rb);
         this.conversations = new ConversationsApi(this.rb);
@@ -57,10 +79,14 @@ export class GraphNodeClient {
         this.appleAuth = new AppleAuthApi(GRAPHNODE_BASE_URL);
         this.sync = new SyncApi(this.rb);
         this.ai = new AiApi(this.rb);
+        this.notification = new NotificationApi(this.rb);
     }
     /**
-     * Access Token을 설정합니다.
-     * @param token JWT Access Token 또는 null (로그아웃 시)
+     * Access Token을 동적으로 설정합니다.
+     * - 로그인 후 발급받은 토큰을 수동으로 설정하거나, 로그아웃 시 null로 초기화할 때 사용합니다.
+     * - 쿠키 기반 인증을 사용하는 경우, 이 함수를 호출하지 않아도(null 상태여도) 정상 동작합니다.
+     *
+     * @param token JWT Access Token 문자열 또는 null (초기화)
      */
     setAccessToken(token) {
         this._accessToken = token;

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}