@thinkfree.dev/tfo-sdk 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,133 @@
1
+ # Thinkfree Office SDK
2
+
3
+ 브라우저에 iframe 으로 임베드된 Thinkfree Office 편집기(워드 · 셀 · 쇼)를 postMessage 로 제어하는 JavaScript / TypeScript SDK 입니다.
4
+
5
+ - **개발자 API** — `Office.word` / `Office.cell` / `Office.show` 또는 `getDocument()` 로 문서 객체 모델을 직접 조작
6
+ - **AI 에이전트 통합** — 편집기 모듈이 제공하는 도구 카탈로그를 실행 가능한 도구 배열로 회수 (`getTools`) 하거나 콜백 프레임워크에 자동 등록 (`registerTools`)
7
+ - **타입 완비** — 단일 번들 `index.d.ts` 로 word / cell / show 전 모듈 타입 제공
8
+
9
+ ## 설치
10
+
11
+ ```bash
12
+ npm install @thinkfree.dev/tfo-sdk
13
+ ```
14
+
15
+ ## 요구 사항
16
+
17
+ - **실행 환경**: 브라우저 (DOM 필요 — Node.js 전용 환경은 지원하지 않습니다)
18
+ - **모듈 형식**: ESM 전용 (CommonJS `require()` 미지원 — 필요하면 dynamic `import()` 사용)
19
+ - **TypeScript** (선택): 4.7 이상, `compilerOptions.lib` 에 `"dom"` 포함
20
+
21
+ ## 시작하기
22
+
23
+ 가장 간단한 진입점은 iframe 요소에서 바로 시작하는 `Office.word/cell/show` 입니다.
24
+
25
+ ```ts
26
+ import { Office, ShapePreset } from '@thinkfree.dev/tfo-sdk';
27
+
28
+ const show = Office.show(document.getElementById('office-iframe') as HTMLIFrameElement);
29
+
30
+ await show.whenReady(); // 편집기 부팅 대기 (선택, 기본 한도 60초)
31
+ const slides = await show.getSlides(); // 문서 메서드 직접 호출
32
+ await slides[0].insertShape(ShapePreset.RECT);
33
+ ```
34
+
35
+ - 같은 iframe 요소로 다시 부르면 같은 앱 핸들을 돌려줍니다 (get-or-create — `disconnect()` 전까지).
36
+ - `frameworkOrigin` 은 iframe 의 `src` 에서 자동 유도됩니다. src 가 없거나 `data:` / `blob:` URL 이면 옵션으로 명시하세요.
37
+ - 앱 핸들에 없는 프로퍼티는 `getDocument()` 핸들로 위임됩니다 — `show.getSlides()` 는 `show.getDocument().getSlides()` 와 같습니다.
38
+ - 한 페이지에 여러 iframe(여러 문서)을 띄워도 안전합니다 — 인스턴스별로 응답이 격리됩니다.
39
+ - MS Office.js 를 같은 페이지에서 쓰면 전역 `Office` 와 이름이 겹칩니다 — `import { Office as TfoOffice }` 로 별칭 import 하세요.
40
+
41
+ ### createOffice — 저수준 팩토리
42
+
43
+ `targetWindow` 통신이나 세부 옵션이 필요하면 팩토리를 직접 사용합니다.
44
+
45
+ ```ts
46
+ import { createOffice } from '@thinkfree.dev/tfo-sdk';
47
+
48
+ const office = createOffice({
49
+ module: 'cell', // 'word' | 'cell' | 'show'
50
+ frameworkOrigin: 'https://office.example.com', // 필수 ('*' 금지)
51
+ iframeEl: document.querySelector('iframe') as HTMLIFrameElement, // 또는 targetWindow (택1)
52
+ // timeoutMs: 5000, // 응답 타임아웃 (기본 5000ms)
53
+ });
54
+
55
+ const wb = office.getDocument(); // Cell.Workbook — module 리터럴로 타입 추론
56
+ const ws = await wb.getWorksheet('Sheet1');
57
+ const rg = await ws.getRange('A1:B2');
58
+ const values = await rg.getValues();
59
+
60
+ office.disconnect(); // 연결만 해제 — 편집기·문서는 그대로
61
+ ```
62
+
63
+ ## 문서 핸들 (getDocument)
64
+
65
+ | module | 최상위 핸들 |
66
+ |--------|-------------------------|
67
+ | `word` | `Word.WordDocument` |
68
+ | `cell` | `Cell.Workbook` |
69
+ | `show` | `Show.Document` |
70
+
71
+ 핸들 메서드는 모두 postMessage 왕복이므로 `Promise` 를 반환하며, 다른 엔티티 핸들(`Show.Slide`, `Cell.Worksheet` 등)을 다시 반환할 수 있습니다.
72
+
73
+ cell 핸들은 **경로 참조(lazy)** 입니다: `getWorksheet` / `getRange` 같은 네비게이션 메서드는 통신 없이 하위 핸들을 즉시 반환하고(존재 확인 안 함), `getValues` / `setValues` 같은 실행 메서드를 호출하는 시점에 1왕복으로 경로를 평가합니다. 경로 중간 대상이 없으면 그 호출이 `SDKError` 로 reject 됩니다.
74
+
75
+ ## AI 에이전트 통합
76
+
77
+ 편집기 모듈이 자기 도구 카탈로그를 소유하고(`SDK.toolList`), SDK 는 schema 를 회수해 전달만 합니다.
78
+
79
+ ```ts
80
+ const word = Office.word(iframeEl);
81
+
82
+ // 실행 가능한 도구 배열 — name · description · inputSchema · execute (개발자 기본 경로)
83
+ const tools = await word.getTools({ include: ['insert_text'] });
84
+ const result = await tools[0].execute({ text: 'Hello' }); // 모듈의 MCP CallToolResult
85
+
86
+ // registerTool 콜백을 받는 프레임워크(tf-agent-sdk 등)면 자동 등록
87
+ await word.registerTools(modelContext);
88
+
89
+ // 또는 직접 dispatch (도구 이름은 모듈 카탈로그가 소유)
90
+ await word.execute('insert_text', [{ text: 'Hello' }]);
91
+
92
+ // 모듈 제공 system prompt (제공하지 않는 모듈은 빈 문자열)
93
+ const prompt = await word.getSystemPrompt();
94
+ ```
95
+
96
+ `registerTools` 의 기본 결과 포맷은 MCP shape(`{ content: [{ type: 'text', text }] }`)이며, `formatResult` / `formatError` 옵션으로 바꿀 수 있습니다.
97
+
98
+ ## 에러 처리
99
+
100
+ 실패는 `SDKError` 로 reject 됩니다. 문서 핸들 호출 실패 시 `SDKError.data` 에 구조화 응답(`ApiErrorResponse`)이 실립니다 — message 문자열을 파싱하지 말고 코드로 분기하세요.
101
+
102
+ ```ts
103
+ import { SDKError, type ApiErrorResponse } from '@thinkfree.dev/tfo-sdk';
104
+
105
+ try {
106
+ const ws = wb.getWorksheet('Nope'); // 네비게이션 — 통신 없음 (lazy)
107
+ await ws.getRange('A1').getValues(); // 실행 시점에 경로 평가 → 여기서 reject
108
+ } catch (e) {
109
+ if (e instanceof SDKError && e.data && typeof e.data === 'object') {
110
+ const { error } = e.data as ApiErrorResponse;
111
+ error.code; // 'SHEET_NOT_FOUND' 같은 UPPERCASE_SNAKE 상수
112
+ error.message; // 사람이 읽을 실패 사유
113
+ }
114
+ }
115
+ ```
116
+
117
+ SDK 자체 오류는 `SDK_ERROR_CODE` 상수로 분기합니다 — `INVALID_ARGUMENT` · `TIMEOUT` · `DESTROYED` · `INVALID_RESPONSE` · `NETWORK_ERROR` · `FRAMEWORK_ERROR`.
118
+
119
+ ## 타입
120
+
121
+ - 모듈 네임스페이스 (타입 + 값): `Word.*` · `Cell.*` · `Show.*` — 예: `Show.Slide` 타입, `Word.RangePosition.END` 값
122
+ - 공통 enum (flat, 타입 + 값): `LineDash` · `ShapePreset` · `ShapeZOrder`
123
+ - 주요 타입: `Office<M>` · `OfficeApp` · `OfficeOptions` · `OfficeAppOptions` · `OfficeTool` · `ToolSchema` · `ApiResponse` · `ApiErrorResponse`
124
+
125
+ 타입 정의(`index.d.ts`)는 비공개 구현 저장소의 API JSDoc 에서 생성되어 패키지에 포함됩니다. 이 저장소 단독으로는 빌드·재생성이 지원되지 않습니다.
126
+
127
+ ## 버전
128
+
129
+ 현재 0.x 입니다 — 공개 표면이 마이너 릴리스에서 바뀔 수 있습니다.
130
+
131
+ 런타임에서는 `SDK_VERSION` 상수로 설치된 패키지 버전을 확인할 수 있습니다. 이 값은 매 호출의
132
+ 메시지 envelope 에 `sdkVersion` 으로 자기 신고되어, 편집기 모듈이 도구·API 별 최소 버전 게이트를
133
+ 적용하는 데 쓰입니다 (호환성 협상용 — 보안 경계가 아닙니다).