@thinkfree.dev/tfo-sdk 0.2.0 → 0.2.1
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 +140 -59
- package/dist/index.d.ts +692 -750
- package/dist/index.js +1 -9
- package/dist/index.js.map +1 -1
- package/dist/sdk-api-catalog.json +695 -388
- package/dist/sdk-api-doc.html +1739 -1050
- package/dist/sdk-api-doc.md +330 -252
- package/dist/version.json +4 -4
- package/package.json +23 -2
package/README.md
CHANGED
|
@@ -1,133 +1,214 @@
|
|
|
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
|
+
```
|
|
16
39
|
|
|
17
|
-
|
|
18
|
-
- **모듈 형식**: ESM 전용 (CommonJS `require()` 미지원 — 필요하면 dynamic `import()` 사용)
|
|
19
|
-
- **TypeScript** (선택): 4.7 이상, `compilerOptions.lib` 에 `"dom"` 포함
|
|
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)).
|
|
20
41
|
|
|
21
|
-
##
|
|
42
|
+
## Requirements
|
|
22
43
|
|
|
23
|
-
|
|
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.
|
|
48
|
+
|
|
49
|
+
## Getting started
|
|
50
|
+
|
|
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.
|
|
64
96
|
|
|
65
|
-
|
|
66
|
-
|--------|-------------------------|
|
|
67
|
-
| `word` | `Word.WordDocument` |
|
|
68
|
-
| `cell` | `Cell.Workbook` |
|
|
69
|
-
| `show` | `Show.Document` |
|
|
97
|
+
## Application and document metadata
|
|
70
98
|
|
|
71
|
-
|
|
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.
|
|
72
100
|
|
|
73
|
-
|
|
101
|
+
```ts
|
|
102
|
+
import { Office, OfficeType } from '@thinkfree.dev/tfo-sdk';
|
|
74
103
|
|
|
75
|
-
|
|
104
|
+
const app = Office.word(iframeEl);
|
|
105
|
+
|
|
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.isReadOnly(); // reflects the mode the document actually opened in
|
|
112
|
+
await doc.getFileName(); // 'report.docx' — current name, including renames
|
|
113
|
+
```
|
|
76
114
|
|
|
77
|
-
|
|
115
|
+
- `getApplicationVersion()` (editor server build, async) and `getVersion()` (SDK bundle, sync) are different values.
|
|
116
|
+
- `isReadOnly()` reports the **actual** opened mode, not the mode requested in the URL. Server-enforced viewer mode, forced viewer for protected or unsupported files, and watcher mode all return `true`.
|
|
117
|
+
- Values are not cached. Renames and mode changes are reflected on every call.
|
|
118
|
+
- Against an older editor that does not implement the metadata command, these methods (except the synchronous `getApplicationType()`) reject with `SDKError(TIMEOUT)`.
|
|
119
|
+
|
|
120
|
+
## Document handles (`getDocument`)
|
|
121
|
+
|
|
122
|
+
| module | root handle | from the app handle |
|
|
123
|
+
|--------|-------------|---------------------|
|
|
124
|
+
| `word` | `Word.WordDocument` | `word.getDocument()` |
|
|
125
|
+
| `cell` | `Cell.Workbook` | `cell.getDocument()` · `cell.getWorkbook()` |
|
|
126
|
+
| `show` | `Show.Document` | `show.getDocument()` |
|
|
127
|
+
|
|
128
|
+
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).
|
|
129
|
+
|
|
130
|
+
All root handles share the module-independent methods `isReadOnly()` and `getFileName()` described above.
|
|
131
|
+
|
|
132
|
+
> **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.
|
|
133
|
+
|
|
134
|
+
Spreadsheet handles are **lazy path references**: navigation methods such as `getWorksheet` and `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
|
+
## AI agent integration
|
|
137
|
+
|
|
138
|
+
The editor module owns its tool catalog. The SDK fetches the schemas and hands them to you.
|
|
78
139
|
|
|
79
140
|
```ts
|
|
80
141
|
const word = Office.word(iframeEl);
|
|
81
142
|
|
|
82
|
-
//
|
|
143
|
+
// Executable tools — name · description · inputSchema · execute (the usual developer path)
|
|
83
144
|
const tools = await word.getTools({ include: ['insert_text'] });
|
|
84
|
-
const result = await tools[0].execute({ text: 'Hello' }); //
|
|
145
|
+
const result = await tools[0].execute({ text: 'Hello' }); // the module's MCP CallToolResult
|
|
85
146
|
|
|
86
|
-
// registerTool
|
|
147
|
+
// Frameworks with a registerTool callback (for example the Thinkfree Agent runtime) — register automatically
|
|
87
148
|
await word.registerTools(modelContext);
|
|
88
149
|
|
|
89
|
-
//
|
|
150
|
+
// Or dispatch directly (tool names are owned by the module catalog)
|
|
90
151
|
await word.execute('insert_text', [{ text: 'Hello' }]);
|
|
91
152
|
|
|
92
|
-
//
|
|
153
|
+
// System prompt provided by the module ('' when the module has none)
|
|
93
154
|
const prompt = await word.getSystemPrompt();
|
|
94
155
|
```
|
|
95
156
|
|
|
96
|
-
`registerTools`
|
|
157
|
+
`registerTools` returns results in MCP shape (`{ content: [{ type: 'text', text }] }`) by default. Override with the `formatResult` / `formatError` options.
|
|
158
|
+
|
|
159
|
+
In addition to the module catalog, the tool list contains **two SDK-defined tools**:
|
|
160
|
+
|
|
161
|
+
- `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.
|
|
162
|
+
- `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 }`.
|
|
163
|
+
|
|
164
|
+
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
165
|
|
|
98
|
-
##
|
|
166
|
+
## Error handling
|
|
99
167
|
|
|
100
|
-
|
|
168
|
+
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
169
|
|
|
102
170
|
```ts
|
|
103
171
|
import { SDKError, type ApiErrorResponse } from '@thinkfree.dev/tfo-sdk';
|
|
104
172
|
|
|
105
173
|
try {
|
|
106
|
-
const ws = wb.getWorksheet('Nope'); //
|
|
107
|
-
await ws.getRange('A1').getValues(); //
|
|
174
|
+
const ws = wb.getWorksheet('Nope'); // navigation — no round trip (lazy)
|
|
175
|
+
await ws.getRange('A1').getValues(); // the path is evaluated here → rejects
|
|
108
176
|
} catch (e) {
|
|
109
177
|
if (e instanceof SDKError && e.data && typeof e.data === 'object') {
|
|
110
178
|
const { error } = e.data as ApiErrorResponse;
|
|
111
|
-
error.code; // 'SHEET_NOT_FOUND'
|
|
112
|
-
error.message; //
|
|
179
|
+
error.code; // UPPERCASE_SNAKE constant such as 'SHEET_NOT_FOUND'
|
|
180
|
+
error.message; // human-readable reason
|
|
113
181
|
}
|
|
114
182
|
}
|
|
115
183
|
```
|
|
116
184
|
|
|
117
|
-
SDK
|
|
185
|
+
SDK-level errors use the `SDK_ERROR_CODE` constants: `INVALID_ARGUMENT` · `TIMEOUT` · `DESTROYED` · `INVALID_RESPONSE` · `NETWORK_ERROR` · `FRAMEWORK_ERROR`.
|
|
186
|
+
|
|
187
|
+
## Types
|
|
188
|
+
|
|
189
|
+
- Module namespaces (types and values): `Word.*` · `Cell.*` · `Show.*` — for example the `Show.Slide` type and the `Word.RangePosition.END` value.
|
|
190
|
+
- Shared enums (flat, types and values): `LineDash` · `ShapePreset` · `ShapeZOrder`.
|
|
191
|
+
- Key types: `Office<M>` · `OfficeApp` · `OfficeOptions` · `OfficeAppOptions` · `OfficeTool` · `ToolSchema` · `ApiResponse` · `ApiErrorResponse`.
|
|
192
|
+
|
|
193
|
+
The type definitions (`index.d.ts`) are generated from the API JSDoc in the private implementation repository and shipped with the package.
|
|
118
194
|
|
|
119
|
-
##
|
|
195
|
+
## Security notes
|
|
120
196
|
|
|
121
|
-
-
|
|
122
|
-
-
|
|
123
|
-
-
|
|
197
|
+
- Always pass the exact editor origin. `frameworkOrigin: '*'` is rejected.
|
|
198
|
+
- 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.
|
|
199
|
+
- Release the connection when the page goes away: `window.addEventListener('pagehide', () => app.disconnect())`.
|
|
124
200
|
|
|
125
|
-
|
|
201
|
+
## Versioning
|
|
126
202
|
|
|
127
|
-
|
|
203
|
+
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
204
|
|
|
129
|
-
|
|
205
|
+
## Links
|
|
130
206
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
207
|
+
- Playground (try before installing): <https://playground.developers.thinkfree.com/playground/>
|
|
208
|
+
- Overview: <https://www.developers.thinkfree.com/docs/editor-sdk/>
|
|
209
|
+
- Quickstart: <https://www.developers.thinkfree.com/docs/editor-sdk/quickstart/>
|
|
210
|
+
- Word API: <https://www.developers.thinkfree.com/docs/editor-sdk/word-api/>
|
|
211
|
+
- Spreadsheet API: <https://www.developers.thinkfree.com/docs/editor-sdk/spreadsheet-api/>
|
|
212
|
+
- Presentation API: <https://www.developers.thinkfree.com/docs/editor-sdk/presentation-api/>
|
|
213
|
+
- Document tools and errors: <https://www.developers.thinkfree.com/docs/editor-sdk/tools-and-errors/>
|
|
214
|
+
- 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>
|