SDK

JavaScript SDK를 사용하면 서버 사이드 JavaScript 또는 TypeScript에서 YouViCo API를 쉽게 호출할 수 있습니다. API 키 인증, 타입이 지정된 요청 파라미터와 응답, 타임아웃, 에러 처리, 멀티파트 파일 업로드 헬퍼를 제공합니다.

WARNING

API 키는 비밀 정보입니다. SDK는 신뢰할 수 있는 서버 사이드 코드에서만 사용하고, 브라우저 코드나 공개 저장소에 API 키를 노출하지 마세요.

설치

pnpm

pnpm add @youvico/api

npm

npm install @youvico/api

클라이언트 생성

import { Client } from "@youvico/api";

const client = new Client({
  apiKey: process.env.YOUVICO_API_KEY!,
});

엔드포인트 호출

SDK는 리소스별로 엔드포인트를 묶어 제공합니다.

const projects = await client.projects.search({
  query: "launch",
});

const folders = await client.folders.list("bdbff5de-96d7-468f-9db0-85fe28bd6b62");

const comments = await client.comments.listForFile("FX1234567890ABCD");

API 레퍼런스 페이지는 각 엔드포인트에서 지원하는 CLI, SDK, cURL 예시를 제공하므로 사용 가능한 인터페이스를 선택할 수 있습니다.

파일 업로드

대부분의 파일 업로드는 files.upload를 사용하세요. 멀티파트 업로드 시작, 파트 업로드, 업로드 완료 요청을 SDK가 처리합니다.

const uploaded = await client.files.upload("bdbff5de-96d7-468f-9db0-85fe28bd6b62", {
  name: "launch.mp4",
  path: "/Users/me/videos/launch.mp4",
});

data 옵션으로 Blob, Buffer, ArrayBuffer, Uint8Array, string도 전달할 수 있습니다.

댓글 첨부파일 업로드

파일 댓글에는 commentAttachments.uploadForFile, 프로젝트 댓글에는 commentAttachments.uploadForProject를 사용하세요. 이 헬퍼는 멀티파트 업로드를 시작하고, 모든 파트를 업로드한 뒤 첨부파일 업로드를 완료합니다.

이 헬퍼는 path와 data 입력을 지원합니다. data에는 파일 업로드와 마찬가지로 Blob, Buffer, ArrayBuffer, Uint8Array, string을 전달할 수 있습니다.

const attachment = await client.commentAttachments.uploadForFile("FX1234567890ABCD", {
  name: "review-note.pdf",
  path: "/Users/me/documents/review-note.pdf",
});

await client.comments.createForFile("FX1234567890ABCD", {
  content: "검토 노트를 추가했습니다.",
  attachments: [{ id: attachment.id }],
});

에러 처리

성공하지 못한 API 응답은 YouvicoError 예외를 던집니다.

import { YouvicoError } from "@youvico/api";

try {
  await client.projects.get("bdbff5de-96d7-468f-9db0-85fe28bd6b62");
} catch (error) {
  if (error instanceof YouvicoError) {
    console.error(error.status, error.code, error.message);
  }

  throw error;
}

클라이언트 옵션

const client = new Client({
  apiKey: process.env.YOUVICO_API_KEY!,
  timeoutMs: 30_000,
});

옵션	필수	설명
apiKey	예	요청 인증에 사용할 YouViCo API 키
baseUrl	아니요	API Base URL 재정의
fetch	아니요	사용자 정의 fetch 구현
timeoutMs	아니요	요청 제한 시간(밀리초)
headers	아니요	모든 요청에 추가할 헤더