설치와 진입점

@edicus/sdk는 브라우저용 패키지입니다. 임포트 경로가 셋이고, 경로마다 실행 환경과 내보내는 것이 다릅니다.

설치

npm install @edicus/sdk@3.0.0-alpha.2

pnpm add @edicus/sdk@3.0.0-alpha.2

yarn add @edicus/sdk@3.0.0-alpha.2

알파 기간에는 버전을 정확히 적어 설치하세요. 버전 없이 설치하면 npm의 latest 태그가 가리키는 버전을 받습니다. 런타임 의존성이 없습니다. TypeScript strict로 작성돼 있어 타입이 함께 따라옵니다.

ESM 전용 패키지입니다. CommonJS 빌드가 없어 require('@edicus/sdk')로는 불러올 수 없습니다. import를 쓰세요. Node.js로 빌드하거나 테스트한다면 18 이상이 필요합니다(engines.node >= 18).

세 가지 진입점

경로	환경	내보내는 것
`@edicus/sdk`	브라우저	`createEdicusClient`, `Session` 계열 클래스, action 상수, `SDK_VERSION`
`@edicus/sdk/types`	둘 다	편집기 메시지, 띄우기 옵션, VDP 타입과 action 이름 런타임 상수
`@edicus/sdk/legacy`	브라우저	`edicusSDK`. v2 호환 표면입니다

서버용 진입점은 없습니다. 토큰 발급, 프로젝트 조회, 주문 처리는 HTTP 엔드포인트를 직접 호출해서 합니다. Server API 호출하기를 보세요.

`@edicus/sdk` (브라우저)

편집기, TnView, Preview를 띄웁니다.

import { createEdicusClient } from '@edicus/sdk'

const edicus = createEdicusClient({
  baseUrl: 'https://editor.edicus.io', // 기본값입니다. 생략할 수 있습니다
})

createEdicusClient()는 window나 document를 즉시 건드리지 않습니다. SSR 환경에서 모듈을 임포트해도 안전하고, 실제 iframe은 createProject 같은 띄우기 메서드를 부르는 시점에만 마운트됩니다.

`@edicus/sdk/types` (타입)

편집기와 주고받는 메시지의 타입(이벤트와 커맨드 payload, Envelope), 띄우기 옵션 타입, VDP 타입을 여기서 가져옵니다. 같은 타입은 @edicus/sdk에서도 다시 내보냅니다.

import type { EditorEventMap, SaveDocReport, VariableDataRow, CreateProjectOptions } from '@edicus/sdk/types'

이 경로에는 아래의 action 이름 상수 배열 여섯 개가 런타임 값으로 들어 있습니다. window나 document를 쓰지 않으므로 서버 코드에서 임포트해도 됩니다.

서버 응답 타입(Project 등)은 이 경로에서 빠졌습니다. 서버 요청과 응답의 타입이 필요하면 Server API의 OpenAPI 문서에서 직접 생성하세요.

npx openapi-typescript https://api.edicus.io/v2/openapi.json -o edicus-server-api.d.ts

action 이름의 런타임 상수 배열도 여기서 재수출합니다. 알려진 action인지 검사할 때 씁니다.

import { EDITOR_EVENT_ACTIONS, EDITOR_COMMAND_ACTIONS } from '@edicus/sdk/types'

EDITOR_EVENT_ACTIONS, EDITOR_COMMAND_ACTIONS, TNVIEW_EVENT_ACTIONS, TNVIEW_COMMAND_ACTIONS, PREVIEW_EVENT_ACTIONS, PREVIEW_COMMAND_ACTIONS 여섯 개가 있습니다.

`@edicus/sdk/legacy` (v2 호환)

v2(edicus-sdk-v2.js)와 같은 이름, 같은 콜백 모양을 그대로 제공합니다.

import { edicusSDK } from '@edicus/sdk/legacy'
const editor = edicusSDK.init({})

새로 시작하신다면 이 경로 대신 @edicus/sdk를 쓰세요. 자세한 내용은 SDK v2에서 옮기기에 있습니다.

`<script>` 태그로 쓰기

번들러 없이 쓰려면 CDN의 IIFE 빌드를 씁니다. 이 빌드는 @edicus/sdk/legacy를 window.edicusSDK에 붙입니다.

<script src="https://cdn.jsdelivr.net/npm/@edicus/sdk@3.0.0-alpha.2/dist/edicus-sdk.iife.js"></script>

지금은 정확한 버전(@3.0.0-alpha.2)을 적어 주세요. @3 같은 버전 범위는 알파 같은 프리릴리스를 고르지 않으므로, 3.0.0 정식 버전이 나오기 전에는 파일을 찾지 못합니다. 정식 버전이 나온 뒤에는 major 버전(@3)만 고정해서 쓰시기를 권합니다.

버전 확인

import { SDK_VERSION } from '@edicus/sdk'
console.log(SDK_VERSION)

@edicus/sdk v3은 아직 알파(3.0.0-alpha.2)입니다. 3.0.0 정식 발행 전까지 API가 바뀔 수 있습니다.

패키지에 함께 들어 있는 문서

설치하면 node_modules/@edicus/sdk/ 안에 한국어 가이드(docs/*.md)와 CHANGELOG.md, 에이전트와 LLM용 API 지도인 llms.txt가 함께 들어옵니다. 웹에 접속하지 않고도 설치한 버전의 API를 확인할 수 있습니다.

시작하기

개념

편집기 SDK

서버 연동

레퍼런스

설치

세 가지 진입점

`@edicus/sdk` (브라우저)

`@edicus/sdk/types` (타입)

`@edicus/sdk/legacy` (v2 호환)

`<script>` 태그로 쓰기

버전 확인

패키지에 함께 들어 있는 문서

다음 단계

편집기 띄우기

세션 API

​설치

​세 가지 진입점

​@edicus/sdk (브라우저)

​@edicus/sdk/types (타입)

​@edicus/sdk/legacy (v2 호환)

​<script> 태그로 쓰기

​버전 확인

​패키지에 함께 들어 있는 문서

​다음 단계

편집기 띄우기

세션 API

설치

세 가지 진입점

`@edicus/sdk` (브라우저)

`@edicus/sdk/types` (타입)

`@edicus/sdk/legacy` (v2 호환)

`<script>` 태그로 쓰기

버전 확인

패키지에 함께 들어 있는 문서

다음 단계