ainote

테마

@ainote/sdk 레퍼런스 ​

npm — npm에 공개됨.

bash
npm install @ainote/sdk

클라이언트 ​

ts
import { AiNote } from '@ainote/sdk';

const ai = new AiNote({
  apiKey,        // 또는 auth: { type:'bearer'|'mcpKey', ... }
  baseUrl,       // 기본 https://api.ainote.dev
  userAgent,     // 기본 @ainote/sdk/<version>
  maxRetries,    // 기본 2 — 멱등(GET/HEAD/DELETE) 요청만 429/5xx 지수 백오프 재시도. 쓰기·MCP는 재시도 안 함
  fetchImpl,     // 커스텀 fetch 주입 (테스트/프록시)
});

REST 리소스 (타입 있음, Bearer) ​

ai.tasks ​

메서드HTTP반환
list(query?)GET /api/tasks{ data: Task[], meta? }
listAll(query?)(페이지 순회)AsyncGenerator<Task>
get(id)GET /api/tasks/:idTask
create(input)POST /api/tasksTask
update(id, input)PATCH /api/tasks/:idTask
delete(id)DELETE /api/tasks/:idvoid

필터: category_id, completed, is_important, kanban_status, due_date_from, due_date_to, sort_by, sort_order, page, per_page.

ai.categories ​

list() / get(id) / create(input) / update(id, input) / delete(id).

ai.papers ​

list(query?) / get(id) / create(input) / update(id, input) / delete(id) / publish(id, published).

Paper 타입은 실제 paper_json 응답에 맞춰져 있습니다(folder/_count/source_url/is_link_note/ai_*). 생성 OpenAPI 스키마(DB 모델)와는 다름.

MCP 미러 (McpKey 또는 Bearer) ​

REST에 없는 vault/파일동기화/핸드오프/dev-docs용. 응답은 정직하게 세 형태로 노출됩니다 — { content, text, resources }.

ts
const { content, text, resources } = await ai.mcp.call('list_tasks', { limit: 1 });
// text       → 사람이 읽는 문자열 (모든 text-type content 합침)
// resources  → 구조화 JSON 배열 (resource-type content 의 JSON payload 파싱; 없으면 [])
// content    → 원본 content 배열 (가공 전)
  • ai.vault.{list, create, clone, sync, connectStatus}
  • ai.sync.{push, pull, list, diff, merge, pendingConflicts}

프로그램으로 동기화를 다룰 땐 text(사람용)가 아니라 resources(기계용 JSON)를 파싱하세요.

에러 클래스 ​

AiNoteError ← AiNoteApiError ← AuthError(401/403) · NotFoundError(404) · ValidationError(422, .fieldErrors) · RateLimitError(429, .retryAfterMs).

MCP 에러 주의: ai.mcp/ai.vault/ai.sync 도구 실패는 JSON-RPC 에러가 HTTP 200 본문에 담겨 옵니다. SDK는 AiNoteApiError를 던지되 status===200, code는 JSON-RPC 에러코드입니다 — e.status>=400이 아니라 에러 클래스로 분기하세요.

ts
import { ValidationError } from '@ainote/sdk';
try { await ai.tasks.create({ content: '' }); }
catch (e) { if (e instanceof ValidationError) console.log(e.fieldErrors); }

v0.1 범위 ​

  • REST: tasks, categories, papers
  • MCP 미러: vault, sync, 임의 mcp.call
  • 미포함: 로그인 헬퍼, 알림/캘린더/텔레그램 등 (필요 시 추가)