@thinkfree.dev/tfo-sdk 0.2.0 → 0.2.2
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 +143 -59
- package/dist/apiReference.generated.js +19572 -0
- package/dist/apiReference.generated.js.map +1 -0
- package/dist/index.d.ts +2948 -1724
- package/dist/index.js +869 -49
- package/dist/index.js.map +1 -1
- package/dist/sdk-api-doc.html +13077 -8502
- package/dist/sdk-api-doc.ko.md +4201 -0
- package/dist/sdk-api-doc.md +2951 -2370
- package/dist/version.json +4 -4
- package/package.json +25 -5
- package/dist/sdk-api-catalog.json +0 -8769
package/README.md
CHANGED
|
@@ -1,133 +1,217 @@
|
|
|
1
|
-
# Thinkfree
|
|
1
|
+
# Thinkfree Editor SDK (`@thinkfree.dev/tfo-sdk`)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A JavaScript / TypeScript SDK for controlling a Thinkfree Office editor (Word, Spreadsheet, Presentation) that is embedded in your web page as an iframe. The SDK talks to the editor over exact-origin `postMessage`; your page never touches the editor's internals.
|
|
4
4
|
|
|
5
|
-
-
|
|
6
|
-
- **AI
|
|
7
|
-
-
|
|
5
|
+
- **Document API** — get an app handle with `Office.word` / `Office.cell` / `Office.show`, then work on the document object model through `getDocument()`.
|
|
6
|
+
- **AI agent integration** — fetch the editor's tool catalog as executable tools (`getTools`) or register them into a tool-calling framework (`registerTools`).
|
|
7
|
+
- **Fully typed** — one bundled `index.d.ts` covers the Word, Spreadsheet, and Presentation APIs.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
> **Private developer preview.** This is a 0.x release. The public surface may change between minor versions.
|
|
10
|
+
|
|
11
|
+
## Try it first
|
|
12
|
+
|
|
13
|
+
You can run the SDK against a live document before installing anything.
|
|
14
|
+
|
|
15
|
+
- **Playground** — <https://playground.developers.thinkfree.com/playground/>: an in-browser console with a sample Word, Spreadsheet, or Presentation document. Pick a module, load an example, and run it. The code you write there is the same code you ship with this package.
|
|
16
|
+
- **Overview** — <https://www.developers.thinkfree.com/docs/editor-sdk/>: what the SDK does, how the pieces fit, and how to open a document.
|
|
17
|
+
|
|
18
|
+
Module API references:
|
|
19
|
+
|
|
20
|
+
| module | reference |
|
|
21
|
+
|--------|-----------|
|
|
22
|
+
| Word (`Office.word`) | <https://www.developers.thinkfree.com/docs/editor-sdk/word-api/> |
|
|
23
|
+
| Spreadsheet (`Office.cell`) | <https://www.developers.thinkfree.com/docs/editor-sdk/spreadsheet-api/> |
|
|
24
|
+
| Presentation (`Office.show`) | <https://www.developers.thinkfree.com/docs/editor-sdk/presentation-api/> |
|
|
25
|
+
|
|
26
|
+
## Installation
|
|
10
27
|
|
|
11
28
|
```bash
|
|
12
29
|
npm install @thinkfree.dev/tfo-sdk
|
|
13
30
|
```
|
|
14
31
|
|
|
15
|
-
|
|
32
|
+
Without a bundler, load the ESM build through an import map so that `import ... from "@thinkfree.dev/tfo-sdk"` resolves in the browser:
|
|
33
|
+
|
|
34
|
+
```html
|
|
35
|
+
<script type="importmap">
|
|
36
|
+
{ "imports": { "@thinkfree.dev/tfo-sdk": "./node_modules/@thinkfree.dev/tfo-sdk/dist/index.js" } }
|
|
37
|
+
</script>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
If you copy the SDK files instead of installing the package, ship `apiReference.generated.js` next to `index.js`. It is a lazily loaded chunk used by the `get_api_reference` tool (see [AI agent integration](#ai-agent-integration)).
|
|
41
|
+
|
|
42
|
+
## Requirements
|
|
16
43
|
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
- **TypeScript** (
|
|
44
|
+
- **Runtime**: a browser (the SDK needs the DOM; Node.js-only environments are not supported).
|
|
45
|
+
- **Module format**: ESM only. CommonJS `require()` is not supported; use dynamic `import()` if needed.
|
|
46
|
+
- **TypeScript** (optional): 4.7 or later, with `"dom"` in `compilerOptions.lib`.
|
|
47
|
+
- **Editor**: a Thinkfree Office deployment that you can open in an iframe. The SDK does not host or open documents by itself.
|
|
20
48
|
|
|
21
|
-
##
|
|
49
|
+
## Getting started
|
|
22
50
|
|
|
23
|
-
|
|
51
|
+
The simplest entry point is `Office.word` / `Office.cell` / `Office.show`, called with the iframe element that hosts the editor. The returned object is an **app handle** that represents the editor application. The document object model comes from `getDocument()`.
|
|
24
52
|
|
|
25
53
|
```ts
|
|
26
54
|
import { Office, ShapePreset } from '@thinkfree.dev/tfo-sdk';
|
|
27
55
|
|
|
28
56
|
const show = Office.show(document.getElementById('office-iframe') as HTMLIFrameElement);
|
|
29
57
|
|
|
30
|
-
await show.whenReady();
|
|
31
|
-
const
|
|
58
|
+
await show.whenReady(); // wait for the editor to boot (optional, default limit 60 s)
|
|
59
|
+
const doc = show.getDocument(); // Show.Document — the root handle (synchronous, no round trip)
|
|
60
|
+
const slides = await doc.getSlides();
|
|
32
61
|
await slides[0].insertShape(ShapePreset.RECT);
|
|
33
62
|
```
|
|
34
63
|
|
|
35
|
-
|
|
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 하세요.
|
|
64
|
+
Things to know:
|
|
40
65
|
|
|
41
|
-
|
|
66
|
+
- Calling `Office.x(iframe)` again with the same iframe element returns the same app handle (get-or-create) until you call `disconnect()`.
|
|
67
|
+
- `frameworkOrigin` is derived from the iframe's `src`. Pass it explicitly when the iframe has no `src`, or uses a `data:` / `blob:` URL.
|
|
68
|
+
- The app handle (`Office.show(el)`) and the document (`show.getDocument()`) are separate objects. Document methods such as `getSlides()` live on the document handle only; they are not proxied through the app handle.
|
|
69
|
+
- Multiple iframes (multiple documents) on one page are safe. Responses are isolated per instance.
|
|
70
|
+
- If MS Office.js is loaded on the same page, the global `Office` name collides. Import with an alias: `import { Office as TfoOffice } from '@thinkfree.dev/tfo-sdk'`.
|
|
42
71
|
|
|
43
|
-
`
|
|
72
|
+
### `createOffice` — low-level factory
|
|
73
|
+
|
|
74
|
+
Use the factory directly when you need `targetWindow` transport or explicit options.
|
|
44
75
|
|
|
45
76
|
```ts
|
|
46
77
|
import { createOffice } from '@thinkfree.dev/tfo-sdk';
|
|
47
78
|
|
|
48
79
|
const office = createOffice({
|
|
49
80
|
module: 'cell', // 'word' | 'cell' | 'show'
|
|
50
|
-
frameworkOrigin: 'https://office.example.com', //
|
|
51
|
-
iframeEl: document.querySelector('iframe') as HTMLIFrameElement, //
|
|
52
|
-
// timeoutMs: 5000, //
|
|
81
|
+
frameworkOrigin: 'https://office.example.com', // required; '*' is rejected
|
|
82
|
+
iframeEl: document.querySelector('iframe') as HTMLIFrameElement, // or targetWindow (pick one)
|
|
83
|
+
// timeoutMs: 5000, // per-call response timeout (default 5000 ms)
|
|
53
84
|
});
|
|
54
85
|
|
|
55
|
-
const wb = office.getDocument(); // Cell.Workbook —
|
|
86
|
+
const wb = office.getDocument(); // Cell.Workbook — typed from the module literal
|
|
56
87
|
const ws = await wb.getWorksheet('Sheet1');
|
|
57
88
|
const rg = await ws.getRange('A1:B2');
|
|
58
89
|
const values = await rg.getValues();
|
|
59
90
|
|
|
60
|
-
office.
|
|
91
|
+
office.getVersion(); // SDK bundle version, e.g. '0.2.0' — synchronous, no connection needed
|
|
92
|
+
office.disconnect(); // releases the connection only; the editor and document stay as they are
|
|
61
93
|
```
|
|
62
94
|
|
|
63
|
-
|
|
95
|
+
> `getVersion()` returns the installed SDK library version (the same value the SDK reports as `sdkVersion` in every message envelope). It works after `disconnect()` and is not the version of the connected editor.
|
|
96
|
+
|
|
97
|
+
## Application and document metadata
|
|
64
98
|
|
|
65
|
-
|
|
66
|
-
|--------|-------------------------|
|
|
67
|
-
| `word` | `Word.WordDocument` |
|
|
68
|
-
| `cell` | `Cell.Workbook` |
|
|
69
|
-
| `show` | `Show.Document` |
|
|
99
|
+
Both the app handle and the document handle expose metadata. The editor answers these calls, so they behave the same in all three modules.
|
|
70
100
|
|
|
71
|
-
|
|
101
|
+
```ts
|
|
102
|
+
import { Office, OfficeType } from '@thinkfree.dev/tfo-sdk';
|
|
103
|
+
|
|
104
|
+
const app = Office.word(iframeEl);
|
|
72
105
|
|
|
73
|
-
|
|
106
|
+
app.getApplicationType(); // 'word' — synchronous. Equals OfficeType.WORD
|
|
107
|
+
await app.getApplicationName(); // 'Word Processor' — display name
|
|
108
|
+
await app.getApplicationVersion(); // 'V17.0.0' — editor server build (null when the deployment does not expose it)
|
|
109
|
+
|
|
110
|
+
const doc = app.getDocument();
|
|
111
|
+
await doc.getFileName(); // 'report.docx' — current name, including renames
|
|
112
|
+
```
|
|
74
113
|
|
|
75
|
-
|
|
114
|
+
- `getApplicationVersion()` (editor server build, async) and `getVersion()` (SDK bundle, sync) are different values.
|
|
115
|
+
- Values are not cached. Renames are reflected on every call.
|
|
116
|
+
- Against an older editor that does not implement the metadata command, these methods (except the synchronous `getApplicationType()`) reject with `SDKError(TIMEOUT)`.
|
|
76
117
|
|
|
77
|
-
|
|
118
|
+
## Document handles (`getDocument`)
|
|
119
|
+
|
|
120
|
+
| module | root handle | from the app handle |
|
|
121
|
+
|--------|-------------|---------------------|
|
|
122
|
+
| `word` | `Word.WordDocument` | `word.getDocument()` |
|
|
123
|
+
| `cell` | `Cell.Workbook` | `cell.getDocument()` · `cell.getWorkbook()` |
|
|
124
|
+
| `show` | `Show.Document` | `show.getDocument()` |
|
|
125
|
+
|
|
126
|
+
Every handle method is a `postMessage` round trip and returns a `Promise`. Methods may return further entity handles (`Show.Slide`, `Cell.Worksheet`, and so on).
|
|
127
|
+
|
|
128
|
+
All root handles share the module-independent method `getFileName()` described above.
|
|
129
|
+
|
|
130
|
+
> **Spreadsheet alias** — `cell.getWorkbook()` returns exactly the same `Cell.Workbook` as `cell.getDocument()`. Use `getDocument()` in module-independent code and `getWorkbook()` when spreadsheet vocabulary reads better. `word` and `show` have no alias because their root handles are already document-shaped.
|
|
131
|
+
|
|
132
|
+
**Always `await` every call.** Handles are proxies, so every method returns a `Promise`. Chaining without `await` yields a `Promise<T>`, which breaks both editor completion and the call itself.
|
|
133
|
+
|
|
134
|
+
Spreadsheet handles are **lazy path references**: navigation methods such as `getRange` return child handles immediately without a round trip and without checking that the target exists. The path is evaluated in one round trip when you call an action method such as `getValues` or `setValues`. If an intermediate target does not exist, that call rejects with `SDKError`.
|
|
135
|
+
|
|
136
|
+
`getWorksheet` is the exception — it is **eager**. It takes one round trip and returns a `Worksheet` pinned to that sheet, so the handle keeps pointing at the sheet you asked for even after sheets are moved, inserted, deleted, or edited remotely by someone else. Once that sheet is deleted, later calls reject with `SHEET_NOT_FOUND` instead of silently acting on a neighbouring sheet. A `Range` follows its sheet the same way, while its coordinates stay the snapshot taken when it was created.
|
|
137
|
+
|
|
138
|
+
## AI agent integration
|
|
139
|
+
|
|
140
|
+
The editor module owns its tool catalog. The SDK fetches the schemas and hands them to you.
|
|
78
141
|
|
|
79
142
|
```ts
|
|
80
143
|
const word = Office.word(iframeEl);
|
|
81
144
|
|
|
82
|
-
//
|
|
145
|
+
// Executable tools — name · description · inputSchema · execute (the usual developer path)
|
|
83
146
|
const tools = await word.getTools({ include: ['insert_text'] });
|
|
84
|
-
const result = await tools[0].execute({ text: 'Hello' }); //
|
|
147
|
+
const result = await tools[0].execute({ text: 'Hello' }); // the module's MCP CallToolResult
|
|
85
148
|
|
|
86
|
-
// registerTool
|
|
149
|
+
// Frameworks with a registerTool callback (for example the Thinkfree Agent runtime) — register automatically
|
|
87
150
|
await word.registerTools(modelContext);
|
|
88
151
|
|
|
89
|
-
//
|
|
152
|
+
// Or dispatch directly (tool names are owned by the module catalog)
|
|
90
153
|
await word.execute('insert_text', [{ text: 'Hello' }]);
|
|
91
154
|
|
|
92
|
-
//
|
|
155
|
+
// System prompt provided by the module ('' when the module has none)
|
|
93
156
|
const prompt = await word.getSystemPrompt();
|
|
94
157
|
```
|
|
95
158
|
|
|
96
|
-
`registerTools`
|
|
159
|
+
`registerTools` returns results in MCP shape (`{ content: [{ type: 'text', text }] }`) by default. Override with the `formatResult` / `formatError` options.
|
|
160
|
+
|
|
161
|
+
In addition to the module catalog, the tool list contains **two SDK-defined tools**:
|
|
162
|
+
|
|
163
|
+
- `get_api_reference` — looks up the document API reference (index, details by name, keyword search). The SDK answers locally from a bundled reference; the data lives in a separate chunk, `apiReference.generated.js`, loaded on first use.
|
|
164
|
+
- `execute_script` — runs a JavaScript snippet inside the editor so multi-step or repetitive edits happen in one call. It reports without throwing, as `{ ok, status, logs }`.
|
|
165
|
+
|
|
166
|
+
Keep the tool set small and task-specific with `include`. See the guide on [document tools and errors](https://www.developers.thinkfree.com/docs/editor-sdk/tools-and-errors/) for framework-specific schema mappings, and the [Editor AI SDK](https://www.developers.thinkfree.com/docs/editor-ai-sdk/) docs for a complete tool-calling loop.
|
|
97
167
|
|
|
98
|
-
##
|
|
168
|
+
## Error handling
|
|
99
169
|
|
|
100
|
-
|
|
170
|
+
Failures reject with `SDKError`. When a document handle call fails, `SDKError.data` carries the structured response (`ApiErrorResponse`). Branch on the code; do not parse the message string.
|
|
101
171
|
|
|
102
172
|
```ts
|
|
103
173
|
import { SDKError, type ApiErrorResponse } from '@thinkfree.dev/tfo-sdk';
|
|
104
174
|
|
|
105
175
|
try {
|
|
106
|
-
const ws = wb.getWorksheet('Nope');
|
|
107
|
-
await ws.getRange('A1')
|
|
176
|
+
const ws = await wb.getWorksheet('Nope'); // eager — this call already rejects
|
|
177
|
+
const rg = await ws.getRange('A1');
|
|
178
|
+
await rg.getValues();
|
|
108
179
|
} catch (e) {
|
|
109
180
|
if (e instanceof SDKError && e.data && typeof e.data === 'object') {
|
|
110
181
|
const { error } = e.data as ApiErrorResponse;
|
|
111
|
-
error.code; // 'SHEET_NOT_FOUND'
|
|
112
|
-
error.message; //
|
|
182
|
+
error.code; // UPPERCASE_SNAKE constant such as 'SHEET_NOT_FOUND'
|
|
183
|
+
error.message; // human-readable reason
|
|
113
184
|
}
|
|
114
185
|
}
|
|
115
186
|
```
|
|
116
187
|
|
|
117
|
-
SDK
|
|
188
|
+
SDK-level errors use the `SDK_ERROR_CODE` constants: `INVALID_ARGUMENT` · `TIMEOUT` · `DESTROYED` · `INVALID_RESPONSE` · `NETWORK_ERROR` · `FRAMEWORK_ERROR`.
|
|
189
|
+
|
|
190
|
+
## Types
|
|
191
|
+
|
|
192
|
+
- Module namespaces (types and values): `Word.*` · `Cell.*` · `Show.*` — for example the `Show.Slide` type and the `Word.RangePosition.END` value.
|
|
193
|
+
- Shared enums (flat, types and values): `LineDash` · `ShapePreset` · `ShapeZOrder`.
|
|
194
|
+
- Key types: `Office<M>` · `OfficeApp` · `OfficeOptions` · `OfficeAppOptions` · `OfficeTool` · `ToolSchema` · `ApiResponse` · `ApiErrorResponse`.
|
|
195
|
+
|
|
196
|
+
The type definitions (`index.d.ts`) are generated from the API JSDoc in the private implementation repository and shipped with the package.
|
|
118
197
|
|
|
119
|
-
##
|
|
198
|
+
## Security notes
|
|
120
199
|
|
|
121
|
-
-
|
|
122
|
-
-
|
|
123
|
-
-
|
|
200
|
+
- Always pass the exact editor origin. `frameworkOrigin: '*'` is rejected.
|
|
201
|
+
- The SDK does not send anything to a model provider by itself. If you forward document-read results to an LLM, document content leaves the browser; your application controls what is sent, authorization, and user approval.
|
|
202
|
+
- Release the connection when the page goes away: `window.addEventListener('pagehide', () => app.disconnect())`.
|
|
124
203
|
|
|
125
|
-
|
|
204
|
+
## Versioning
|
|
126
205
|
|
|
127
|
-
|
|
206
|
+
This package is at 0.x; the public surface may change in minor releases. At runtime the `SDK_VERSION` constant exposes the installed version. The SDK also reports it as `sdkVersion` in every message envelope so the editor can apply per-tool and per-API minimum-version gates (compatibility negotiation, not a security boundary).
|
|
128
207
|
|
|
129
|
-
|
|
208
|
+
## Links
|
|
130
209
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
210
|
+
- Playground (try before installing): <https://playground.developers.thinkfree.com/playground/>
|
|
211
|
+
- Overview: <https://www.developers.thinkfree.com/docs/editor-sdk/>
|
|
212
|
+
- Quickstart: <https://www.developers.thinkfree.com/docs/editor-sdk/quickstart/>
|
|
213
|
+
- Word API: <https://www.developers.thinkfree.com/docs/editor-sdk/word-api/>
|
|
214
|
+
- Spreadsheet API: <https://www.developers.thinkfree.com/docs/editor-sdk/spreadsheet-api/>
|
|
215
|
+
- Presentation API: <https://www.developers.thinkfree.com/docs/editor-sdk/presentation-api/>
|
|
216
|
+
- Document tools and errors: <https://www.developers.thinkfree.com/docs/editor-sdk/tools-and-errors/>
|
|
217
|
+
- Editor AI SDK (LLM tool-calling on top of this package): <https://www.developers.thinkfree.com/docs/editor-ai-sdk/> · npm: <https://www.npmjs.com/package/@thinkfree.dev/tfo-ai-sdk>
|