샌드박스

HTML, CSS, JavaScript 코드를 작성해 노드를 빌드할 수 있는 노드입니다.

---

설명

샌드박스 노드는 코드 에디터에 직접 HTML, CSS, JavaScript 코드를 입력하고 실행할 수 있습니다.

주요 기능:

• 코드 입력 및 실행: HTML, CSS, JavaScript 코드를 직접 작성하고 실행할 수 있습니다
• 실시간 프리뷰: 코드의 실행 결과를 바로 확인할 수 있는 프리뷰 창이 제공됩니다
• 콘솔 로깅: JavaScript를 통해 데이터를 콘솔에 로그하여, 코드 실행 중 발생하는 데이터를 확인할 수 있습니다

---

포트 구성

입력 포트

• 데이터셋: JavaScript에서 함수로 가져올 수 있는 데이터셋

출력 포트

• 데이터셋: sendDataToOutput 함수로 전달한 데이터셋

---

속성

입력 포트 추가

샌드박스 노드 편집 화면의 Settings 탭에서 샌드박스 노드의 입력 포트를 추가할 수 있습니다.

---

JS 에디터에서 사용 가능한 함수

분류	함수
입력 데이터	getDataset, getAllDataset, getDownloadURL
노드 실행·조회	runNode, runNodeAndWait, getNodeStatus, getNodeIds, updateNodeProperties, getNodeOutputDataset
출력	sendDataToOutput, resetSandboxOutput
애플리케이션·사용자	changeApplicationMenu, getUserInfo, logout
파일	uploadFile, getFile, getImageUrl, getAudioUrl, decryptFile, downloadGoogleDriveFile

오류 처리

비동기 함수는 실패하면 Error로 reject 되며, 실패 사유는 error.message에 담깁니다. try...catch 또는 .catch()로 처리하세요. 응답이 오지 않으면 함수별 제한 시간(기본 30초)이 지난 뒤 sandbox api timeout 오류가 발생합니다.

getDataset

입력 포트와 연결된 노드의 데이터를 가져오는 비동기 함수입니다.

getDataset(options: {
  target?: number;
  limit?: number;
  page?: number;
  sortedBy?: string;
  ascending?: boolean;
}): Promise<Record<string, any>[]>

옵션 설명:

• target (number, optional): 입력 포트 번호 (기본값: 1, 최소값: 1)
• limit (number, optional): 가져올 행 개수 (기본값: 20, 최대값: 1000, 최소값: 1)
• page (number, optional): 페이지 번호 (기본값: 1, 최소값: 1)
• sortedBy (string, optional): 정렬 기준 필드명
• ascending (boolean, optional): 오름차순 여부 (기본값: true)

예시:

getDataset({ limit: 10, page: 2 }).then((response) => {
  console.log(response);
});

비동기 처리

getDataset은 비동기 함수이므로 await 또는 .then()을 사용해야 합니다.

getAllDataset

입력 포트와 연결된 노드의 전체 데이터를 가져오는 비동기 함수입니다. (페이지네이션 없이 모든 데이터를 가져옵니다)

getAllDataset(
    target?: number,
    sortedBy?: string,
    ascending?: boolean
): Promise<Record<string, any>[]>

옵션 설명:

• target (number, optional): 입력 포트 번호 (기본값: 1, 최소값: 1)
• sortedBy (string, optional): 정렬 기준 필드명
• ascending (boolean, optional): 오름차순 여부 (기본값: true)

예시:

// await 사용 (async 함수 내부에서)
const data = await getAllDataset();
console.log("전체 데이터:", data);
console.log("데이터 개수:", data.length);

// .then() 사용
getAllDataset().then((data) => {
  console.log("전체 데이터:", data);
  console.log("데이터 개수:", data.length);
});

비동기 처리 및 성능

• getAllDataset은 비동기 함수이므로 await 또는 .then()을 사용해야 합니다
• 페이지네이션 없이 모든 데이터를 가져오므로, 대량의 데이터가 있을 경우 성능에 영향을 줄 수 있습니다. 필요한 경우 getDataset의 limit과 page 옵션을 사용하세요
• 내부적으로 1,000행씩 나누어 조회합니다. 조회 중 오류가 발생하면 예외 대신 빈 배열([])을 반환하고 오류는 콘솔에만 출력되므로, 빈 결과가 "데이터 없음"인지 "조회 실패"인지 콘솔에서 확인하세요

runNode

캔버스 상의 다른 노드를 프로그래밍적으로 실행시키는 비동기 함수입니다.

runNode(options: {nodeId: string;}): Promise<boolean>

옵션 설명:

• nodeId (string, required): 실행할 노드의 ID

node Id 확인 방법

캔버스에서 해당 노드를 우클릭 → 노드 ID 복사에서 확인할 수 있습니다.

예시:

// 특정 노드를 실행
await runNode({ nodeId: "node-preprocess-1234" });

실행 완료를 기다리지 않습니다

runNode는 실행 요청을 보낸 뒤 바로 끝납니다. 실행 결과를 이어서 읽어야 한다면 완료까지 기다리는 runNodeAndWait를 사용하세요.

runNodeAndWait

캔버스 상의 다른 노드를 실행하고, 실행이 끝날 때까지 기다리는 비동기 함수입니다.

runNodeAndWait(options: {
    nodeId: string;
    timeoutMs?: number;
}): Promise<{ status: 'complete' | 'failed' | 'not start' }>

옵션 설명:

• nodeId (string, required): 실행할 노드의 ID
• timeoutMs (number, optional): 실행 완료를 기다릴 최대 시간(밀리초) (기본값: 60000)

반환값:

• { status: 'complete' }: 실행이 정상적으로 완료된 상태
• { status: 'failed' }: 실행 중 오류로 실패한 상태
• { status: 'not start' }: 실행 요청은 끝났지만 노드가 실행되지 않은 상태로 남은 경우

예시:

// 저장소 노드를 실행하고, 완료된 뒤 그 결과를 읽습니다
const result = await runNodeAndWait({ nodeId: "node-localDataStorage-1234" });

if (result.status === "complete") {
  const rows = await getNodeOutputDataset({
    nodeId: "node-localDataStorage-1234",
  });
  console.log("행 수:", rows.length);
} else {
  console.error("노드 실행이 실패했습니다.");
}

제한 시간 안에 완료를 확인하지 못하거나, 노드를 찾지 못하거나, 실행 요청 자체가 실패하면 예외가 발생합니다. try...catch로 처리하세요.

try {
  await runNodeAndWait({ nodeId: "node-preprocess-1234", timeoutMs: 120000 });
} catch (error) {
  console.error(error.message); // 예: 노드 실행 완료를 제한 시간 안에 확인하지 못했습니다.
}

이전 실행 결과와 구분합니다

runNodeAndWait는 이번 실행이 시작된 것을 확인한 뒤의 완료만 완료로 인정합니다. 애플리케이션으로 배포한 화면에서는 접속 직후 노드 상태가 이미 complete로 보일 수 있어, 상태만 확인하는 방식으로는 이전 실행 결과를 읽게 됩니다.

getNodeStatus

지정한 노드의 현재 상태를 가져오는 비동기 함수입니다.

getNodeStatus(options: {
    nodeId: string;
}): Promise<'not start' | 'loading' | 'complete' | 'failed'>

옵션 설명:

• nodeId (string, required): 상태를 조회할 노드의 ID

반환값:

• 'not start': 실행되지 않은 상태
• 'loading': 실행 중인 상태
• 'complete': 실행이 정상적으로 완료된 상태
• 'failed': 실행 중 오류로 실패한 상태

예시:

// await 사용 (async 함수 내부에서)
const status = await getNodeStatus({ nodeId: "node-sandbox-1234" });

if (status === "loading") {
  console.log("노드가 아직 실행 중입니다.");
} else if (status === "complete") {
  console.log("노드 실행이 완료되었습니다.");
} else if (status === "failed") {
  console.error("노드 실행이 실패했습니다.");
}

상태 감지

일정 주기로 getNodeStatus를 호출하여 상태 변화를 감지해야 합니다.

runNode로 실행한 노드가 끝나기를 기다리는 용도라면 runNodeAndWait를 사용하세요. 실행 전 상태가 이미 complete인 경우 첫 확인에서 바로 통과해, 이번 실행이 아니라 이전 실행 결과를 읽게 됩니다.

getNodeIds

캔버스에 있는 노드 목록(노드 ID·노드 종류·사용자 지정 이름)을 가져오는 비동기 함수입니다. 노드 ID를 코드에 직접 적지 않고 노드 종류로 찾아야 할 때 사용합니다.

getNodeIds(options: {
  canvas: string;
  name?: string;
}): Promise<{
  nodes: {
    id: string;
    name: string;
    customName: string | null;
  }[];
}>

옵션 설명:

• canvas (string, required): 노드를 조회할 캔버스 ID. 캔버스 주소(URL)의 /canvas/ 뒤에 있는 값입니다
• name (string, optional): 노드 종류 이름으로 필터링합니다 (예: "documentData"). 생략하면 캔버스의 모든 노드를 반환합니다 (그룹 노드 제외)

반환값:

• nodes: 노드 정보 배열
  • id (string): 노드 ID. runNode, getNodeOutputDataset 등 nodeId를 받는 함수에 그대로 사용합니다
  • name (string): 노드 종류 이름
  • customName (string | null): 사용자가 지정한 노드 이름 (없으면 null)

예시:

const { nodes } = await getNodeIds({
  canvas: "6a7c2efd0c36cd3ab26060fd",
  name: "documentData",
});

const target = nodes.find((node) => node.customName === "계약서 업로드");
if (target) {
  await uploadFile({ nodeId: target.id, file });
}

반환값은 배열이 아닙니다

결과는 { nodes: [...] } 형태의 객체입니다. 배열로 가정하고 Array.isArray(result)로 확인하면 항상 빈 목록으로 처리되니, result.nodes를 사용하세요. canvas를 생략하면 오류가 발생합니다.

updateNodeProperties

캔버스의 다른 노드 속성(param) 값을 변경하는 비동기 함수입니다. 변경 후 바로 실행하도록 지정할 수 있습니다.

updateNodeProperties(options: {
  nodeId: string;
  properties: {
    name: string;
    value: any;
    options?: any;
  }[];
  run?: boolean;
}): Promise<boolean>

옵션 설명:

• nodeId (string, required): 속성을 변경할 노드의 ID
• properties (array, required): 변경할 속성 목록
  • name (string): 속성의 내부 이름 (param name)
  • value (any): 설정할 값. 해당 속성이 기대하는 형태(문자열·숫자·배열·객체 등)와 같아야 합니다
  • options (any, optional): 선택지가 있는 속성의 옵션 목록
• run (boolean, optional): 변경 후 노드 실행 여부 (기본값: false)

예시:

// 프롬프트 노드의 질문 프롬프트를 바꾸고 실행
await updateNodeProperties({
  nodeId: "node-prompt-1234",
  properties: [
    { name: "questionPrompt", value: "다음 내용을 세 줄로 요약해 주세요." },
  ],
  run: true,
});

실행 완료를 기다리지 않습니다

run: true로 호출해도 실행 요청만 보내고 바로 끝납니다. 실행 결과가 필요하면 getNodeStatus로 상태를 확인하세요. 직전 실행의 complete 상태가 잠시 남아 있을 수 있으므로, loading을 먼저 확인한 뒤 종료를 기다려야 합니다.

node Id 확인 방법

캔버스에서 해당 노드를 우클릭 → 노드 ID 복사에서 확인할 수 있습니다.

getNodeOutputDataset

다른 노드의 출력 데이터셋을 가져오는 비동기 함수입니다. 대상 노드의 첫 번째 출력 포트 데이터를 조회하며, 페이지네이션 및 정렬 옵션을 지원합니다.

getNodeOutputDataset(options: {
    nodeId: string;
    canvas?: string;
    limit?: number;
    page?: number;
    sortedBy?: string;
    ascending?: boolean;
}): Promise<Record<string, any>[]>

옵션 설명:

• nodeId (string, required): 출력 데이터를 가져올 대상 노드의 ID
• canvas (string, optional): 캔버스 ID (기본값: 현재 캔버스)
• limit (number, optional): 한 번에 가져올 행(row) 수 (기본값: 20)
• page (number, optional): 페이지 번호 (기본값: 1, 최소값: 1)
• sortedBy (string, optional): 정렬 기준 필드명
• ascending (boolean, optional): 오름차순 여부 (기본값: true)

예시:

// 다른 노드의 출력 데이터 100건만 가져오기
const rows = await getNodeOutputDataset({
  nodeId: "node-previous-1234",
  limit: 100,
  page: 1,
});

console.log("이전 노드 출력 데이터:", rows);

출력 포트가 여러 개인 노드

항상 첫 번째 출력 포트의 데이터셋을 조회합니다. 두 번째 이후 출력 포트는 선택할 수 없습니다.

node Id 확인 방법

캔버스에서 해당 노드를 우클릭 → 노드 ID 복사에서 확인할 수 있습니다.

sendDataToOutput

출력 포트와 연결된 노드에 데이터를 전달하는 함수입니다.

sendDataToOutput(data: Record<string, any>[]): void

파라미터:

• data: 다음 노드로 보낼 객체 배열 형식의 데이터

예시:

sendDataToOutput([
  { name: "Alice", age: 28 },
  { name: "Bob", age: 34 },
]);

resetSandboxOutput

샌드박스 노드의 출력 데이터를 초기화하는 함수입니다. nodeId를 전달하지 않으면 현재 샌드박스의 출력 데이터를 초기화하고, nodeId가 있으면 해당 nodeId의 샌드박스 데이터를 초기화합니다.

resetSandboxOutput(nodeId?: string): void

파라미터:

• nodeId (optional): 리셋할 샌드박스 노드의 ID
  • 미전달 시: 현재 샌드박스 아웃풋 리셋
  • 전달 시: 해당 nodeId 샌드박스 아웃풋 리셋

예시:

resetSandboxOutput();

resetSandboxOutput("node-sandbox-1234");

node Id 확인 방법

캔버스에서 해당 노드를 우클릭 → 노드 ID 복사에서 확인할 수 있습니다.

changeApplicationMenu

애플리케이션의 메뉴를 변경하는 함수입니다.

changeApplicationMenu(menuNumber: number): void

파라미터:

• menuNumber (number, required): 이동할 메뉴 번호 (최소값: 1)
  • 첫 번째 메뉴는 1, 두 번째 메뉴는 2입니다
  • 1보다 작은 값을 입력하면 에러가 발생합니다

예시:

// 첫 번째 메뉴로 이동
changeApplicationMenu(1);

// 두 번째 메뉴로 이동
changeApplicationMenu(2);

// 버튼 클릭 시 메뉴 변경
document.getElementById("nextBtn").addEventListener("click", () => {
  changeApplicationMenu(2);
});

getUserInfo

현재 로그인한 사용자의 기본 정보를 가져오는 비동기 함수입니다.

getUserInfo(): Promise<{
    id: string;
    name: string;
    email: string;
    licenseType?: string;
    teamName?: string;
    isTeamOwner?: boolean;
}>

반환값:

• id (string): 사용자 ID
• name (string): 사용자 이름
• email (string): 사용자 이메일
• licenseType (string): 사용자의 라이선스 종류 (없으면 빈 문자열)
• teamName (string): 소속 팀 이름 (없으면 빈 문자열)
• isTeamOwner (boolean): 팀 소유자 여부 (기본값: false)

예시:

// await 사용 (async 함수 내부에서)
const user = await getUserInfo();

if (!user.id) {
  console.log("로그인되지 않은 사용자입니다.");
} else {
  console.log("현재 사용자:", user.name, user.email);
}

비로그인 상태

인증 정보가 없는 경우(비로그인 등) 에러 대신 id, name, email이 모두 빈 문자열인 객체를 반환합니다. 이때 licenseType, teamName, isTeamOwner는 포함되지 않습니다.

logout

현재 로그인한 사용자를 로그아웃시키는 함수입니다. 배포한 애플리케이션에 로그아웃 버튼을 만들 때 사용합니다.

logout(): void

예시:

document.getElementById("logoutBtn").addEventListener("click", () => {
  logout();
});

응답을 기다리지 마세요

logout은 로그아웃 요청만 보내고 결과를 돌려주지 않습니다. await logout()으로 기다리면 30초 뒤 sandbox api timeout 오류가 발생하니, await 없이 호출하세요. 로그아웃 후 화면 이동은 자동으로 일어나지 않습니다.

getDownloadURL

입력 포트와 연결된 데이터셋의 다운로드 URL을 가져오는 비동기 함수입니다.

getDownloadURL(options: {
  target?: number;
  format?: 'csv' | 'xlsx';
}): Promise<{
  downloadUrl: string;
  fileName: string;
}>

옵션 설명:

• target (number, optional): 입력 포트 번호 (기본값: 1, 최소값: 1)
• format (string, optional): 다운로드 파일 포맷 (기본값: 'csv')
  • 'csv': CSV 형식으로 다운로드
  • 'xlsx': Excel 형식으로 다운로드

반환값:

• downloadUrl (string): 데이터셋 다운로드 URL
• fileName (string): 다운로드 파일 이름

예시:

// 기본 사용 (CSV 형식)
const { downloadUrl, fileName } = await getDownloadURL();
console.log("다운로드 URL:", downloadUrl);
console.log("파일명:", fileName);

// Excel 형식으로 다운로드
const excelResult = await getDownloadURL({ format: "xlsx" });

// 특정 입력 포트의 데이터셋 다운로드
const result = await getDownloadURL({ target: 2, format: "csv" });

// 다운로드 링크 생성 예시
const { downloadUrl, fileName } = await getDownloadURL({ format: "xlsx" });
const link = document.createElement("a");
link.href = downloadUrl;
link.download = fileName;
link.click();

비동기 처리

getDownloadURL은 비동기 함수이므로 await 또는 .then()을 사용해야 합니다.

downloadGoogleDriveFile

Google Drive 파일 ID로 해당 파일을 다운로드하는 비동기 함수입니다. 새 탭에서 Google Drive 다운로드 주소를 엽니다.

downloadGoogleDriveFile(fileId: string): Promise<boolean>

파라미터:

• fileId (string, required): Google Drive 파일 ID (공유 링크에서 확인 가능)

예시:

// Google Drive 파일 다운로드
downloadGoogleDriveFile("fileId");

팝업 차단

브라우저가 팝업을 차단하면 popup blocked 오류가 발생합니다. 버튼 클릭 등 사용자 동작 안에서 호출하세요.

uploadFile

파일 업로드 노드에 파일을 업로드하는 비동기 함수입니다. 업로드한 파일은 해당 노드에 바로 반영됩니다.

uploadFile(options: {
  nodeId: string;
  file: File | Blob;
  fileName?: string;
  label?: string;
  run?: boolean;
  overwrite?: boolean;
}): Promise<{
  fileName: string;
  fileKey?: string;
  label?: string;
}>

지원 노드:

노드	업로드 동작
오디오 레코더	녹음 목록에 파일이 추가됩니다. 파일명 생략 시 자동 생성
오디오 데이터	오디오 파일 목록에 추가됩니다. 파일명 생략 시 자동 생성
이미지 데이터	지정한 클래스(label)에 이미지가 추가됩니다. 확장자 포함 파일명 필수
문서 데이터	문서 파일 목록에 추가됩니다. 확장자 포함 파일명 필수

옵션 설명:

• nodeId (string, required): 업로드 대상 노드의 ID
• file (File | Blob, required): 업로드할 파일
• fileName (string, optional): 저장할 파일명. File 객체는 생략 시 파일 이름을 그대로 사용합니다
  • 이미지/문서 데이터 노드는 확장자를 포함한 파일명이 필수입니다 (Blob 업로드 시 반드시 지정)
• label (string, optional): 이미지 데이터 노드 전용 — 업로드할 클래스 이름
  • 없는 이름이면 새 클래스를 생성합니다
  • 생략 시 첫 번째 클래스에 업로드하고, 클래스가 하나도 없으면 Class 1을 생성합니다
• run (boolean, optional): 업로드 완료 후 노드 자동 실행 여부 (기본값: true)
• overwrite (boolean, optional): 덮어쓰기 여부 (기본값: false)
  • false: 같은 이름의 파일이 이미 있으면 이름(1).ext처럼 이름을 자동으로 바꿔 새 파일로 추가합니다
  • true: 노드의 파일 목록이 방금 업로드한 파일 하나로 교체됩니다 (기존 파일은 목록에서 제거)
  • 문서 데이터 노드는 실제 저장되는 파일명이 요청한 이름과 다를 수 있으니 응답의 fileName을 참고하세요

반환값:

• fileName (string): 실제 저장된 파일명
• fileKey (string, optional): 문서 데이터 노드 전용 — 업로드된 파일의 저장 키
• label (string, optional): 이미지 데이터 노드 전용 — 업로드된 클래스 이름

예시:

// 파일 선택 input에서 문서 데이터 노드로 업로드
const file = document.getElementById("file-input").files[0];
const result = await uploadFile({ nodeId: "node-document-1234", file });
console.log("업로드된 파일명:", result.fileName);

// 텍스트로 파일을 만들어 업로드 (Blob은 fileName 필수)
const blob = new Blob(["메모 내용"], { type: "text/plain" });
await uploadFile({
  nodeId: "node-document-1234",
  file: blob,
  fileName: "memo.txt",
});

// 이미지 데이터 노드의 특정 클래스로 업로드
await uploadFile({ nodeId: "node-image-1234", file, label: "강아지" });

// 업로드만 하고 노드는 실행하지 않기
await uploadFile({ nodeId: "node-audio-1234", file, run: false });

// 노드의 파일을 방금 업로드한 파일로 교체 (덮어쓰기)
await uploadFile({ nodeId: "node-document-1234", file, overwrite: true });

👉 샘플 캔버스를 복제해서 파일 업로드 예시를 직접 확인해 볼 수 있습니다.

node Id 확인 방법

캔버스에서 해당 노드를 우클릭 → 노드 ID 복사에서 확인할 수 있습니다.

비동기 처리 및 타임아웃

• uploadFile은 비동기 함수이므로 await 또는 .then()을 사용해야 합니다
• 업로드 요청은 120초 후 타임아웃되며, 지원하지 않는 노드 ID를 전달하면 에러가 발생합니다
• 문서 데이터 노드에 최대 파일 개수가 설정되어 있으면, 개수를 넘는 업로드는 에러가 발생합니다 (overwrite: true는 제외)

getFile

데이터셋 셀에 담긴 파일 키로 파일 내용을 가져오는 비동기 함수입니다. 오디오 데이터·문서 데이터·이미지 데이터 노드의 출력 데이터셋에 있는 파일 키를 사용합니다.

getFile(options: {
  fileId: string;
}): Promise<{
  buffer: ArrayBuffer;
  contentType: string;
}>

옵션 설명:

• fileId (string, required): 파일 키. audioData/, fileData/, imageData/로 시작하는 값만 지원합니다

반환값:

• buffer (ArrayBuffer): 파일 바이트
• contentType (string): 파일의 MIME 타입

예시:

const rows = await getAllDataset();
const { buffer, contentType } = await getFile({ fileId: rows[0].file });

// Blob으로 만들어 다운로드 링크 생성
const url = URL.createObjectURL(new Blob([buffer], { type: contentType }));

비동기 처리 및 타임아웃

• getFile은 비동기 함수이므로 await 또는 .then()을 사용해야 합니다
• 요청은 30초 후 타임아웃됩니다. 지원하지 않는 형식의 키를 전달하면 에러가 발생합니다
• 이미지를 화면에 표시하는 용도라면 getImageUrl이 더 간단합니다

getImageUrl

이미지 데이터 노드의 이미지 키로 화면에 바로 표시할 수 있는 이미지 URL을 가져오는 비동기 함수입니다.

getImageUrl(imageKey: string): Promise<string>

파라미터:

• imageKey (string, required): 이미지 키. imageData/로 시작하는 값만 지원합니다

반환값:

• 이미지의 blob URL (blob:...). <img>의 src에 그대로 사용합니다

예시:

const rows = await getAllDataset();

for (const row of rows) {
  const img = document.createElement("img");
  img.src = await getImageUrl(row.image);
  document.body.appendChild(img);
}

캐시

같은 이미지 키를 다시 요청하면 이전에 만든 URL을 재사용합니다. 반환된 URL은 샌드박스 화면이 닫히면 해제되므로 저장해 두었다가 다른 화면에서 사용할 수 없습니다.

getAudioUrl

오디오 데이터 노드의 오디오 키로 재생할 수 있는 오디오 URL을 가져오는 비동기 함수입니다.

getAudioUrl(audioKey: string): Promise<string>

파라미터:

• audioKey (string, required): 오디오 데이터셋 셀에 담긴 오디오 키

반환값:

• 오디오의 blob URL (blob:...). <audio>의 src에 그대로 사용합니다

예시:

const rows = await getAllDataset();
const audio = document.getElementById("player");
audio.src = await getAudioUrl(rows[0].audio);
audio.play();

decryptFile

파일을 서버로 보내 DRM 복호화를 거친 내용을 돌려받는 비동기 함수입니다. 사용자가 샌드박스 화면에서 선택한 DRM 암호화 문서를 브라우저에서 바로 읽어야 할 때 사용합니다.

decryptFile(options: {
  file: File | Blob;
  fileName?: string;
}): Promise<{
  buffer: ArrayBuffer;
  contentType: string;
}>

옵션 설명:

• file (File | Blob, required): 복호화할 파일
• fileName (string, optional): 확장자를 포함한 파일명. File 객체는 생략 시 파일 이름을 그대로 사용합니다
  • Blob을 전달하거나 파일 이름에 확장자가 없으면 반드시 지정해야 합니다. 확장자가 없으면 서버에 요청하지 않고 에러가 발생합니다

반환값:

• buffer (ArrayBuffer): 복호화된 파일 바이트
• contentType (string): 원본 파일의 MIME 타입 (파일 형식은 바뀌지 않습니다)

동작:

상황	결과
DRM 암호화 파일 (복호화 기능이 켜진 환경)	복호화된 바이트 반환
평문 파일, 또는 복호화 기능이 꺼진 환경	원본 바이트를 그대로 반환
복호화 실패	에러 발생 (원본을 반환하지 않음)

지원 형식:

• 문서: pdf, doc, docx, hwp, hwpx, ppt, pptx
• 표: xls, xlsx, ods, csv, tsv
• 텍스트: txt, md, markdown, json, html, htm, xml
• 소스 코드: java, jsp, js, c, h, cpp, cc, cxx, hpp

이미지·오디오·압축 파일 등 그 밖의 형식은 평문이더라도 에러가 발생합니다.

예시:

// 파일 선택 input으로 받은 엑셀 파일을 복호화해 읽기 (SheetJS를 불러온 경우)
const file = document.getElementById("file-input").files[0];

try {
  const { buffer } = await decryptFile({ file });
  const workbook = XLSX.read(buffer, { type: "array" });
  const rows = XLSX.utils.sheet_to_json(
    workbook.Sheets[workbook.SheetNames[0]],
  );
  console.log("행 수:", rows.length);
} catch (error) {
  console.error(error.message); // 예: report.png: 지원하지 않는 파일 형식입니다: .png
}

제한 사항

• 빈 파일은 에러가 발생합니다
• 파일 크기 상한은 기본 100MB이며, 환경 설정에 따라 다를 수 있습니다. 상한을 넘으면 에러가 발생합니다
• 다른 복호화 요청이 처리 중이면 대기하지 않고 바로 에러가 발생합니다. 잠시 후 다시 시도하세요
• 요청은 180초 후 타임아웃됩니다

저장되지 않습니다

복호화한 내용은 서버의 저장소나 데이터베이스에 남지 않고 호출한 화면에만 전달됩니다. 파일을 노드에 저장하려면 uploadFile을 사용하세요. 문서 데이터 노드로 업로드한 파일은 서버에서 복호화를 따로 거칩니다.

---

JS 에디터에서 사용 가능한 이벤트

node-status-changed

노드 상태 변경을 감지하는 이벤트입니다.

예시:

window.addEventListener("node-status-changed", async (event) => {
  console.log("노드 상태 변경됨!");
  console.log("nodeStatus:", event.detail.nodeStatus); // ✅ loading, complete 등
});