@thinkfree.dev/tfo-sdk 0.3.0 → 0.4.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 CHANGED
@@ -2,11 +2,11 @@
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
- - **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`).
5
+ - **Document API** — get an app handle with `Office.word` / `Office.cell` / `Office.show` (or let the SDK open the editor with `Office.word.load()`), then work on the document object model through `getDocument()`.
6
+ - **AI agent integration** — package the editor's tools, prompt rules and results for your LLM loop (`createOfficeToolkit`), or fetch them as executable tools (`getTools`) and register them into a tool-calling framework (`registerTools`).
7
7
  - **Fully typed** — one bundled `index.d.ts` covers the Word, Spreadsheet, and Presentation APIs.
8
8
 
9
- > **Private developer preview.** This is a 0.x release. The public surface may change between minor versions.
9
+ > **Developer preview.** This is a 0.x release. The public surface may change between minor versions.
10
10
 
11
11
  ## Try it first
12
12
 
@@ -44,7 +44,7 @@ If you copy the SDK files instead of installing the package, ship `apiReference.
44
44
  - **Runtime**: a browser (the SDK needs the DOM; Node.js-only environments are not supported).
45
45
  - **Module format**: ESM only. CommonJS `require()` is not supported; use dynamic `import()` if needed.
46
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.
47
+ - **Editor**: a Thinkfree Office deployment that you can open in an iframe. The SDK does not host documents; your Office or storage integration issues the open URL.
48
48
 
49
49
  ## Getting started
50
50
 
@@ -69,6 +69,23 @@ Things to know:
69
69
  - Multiple iframes (multiple documents) on one page are safe. Responses are isolated per instance.
70
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'`.
71
71
 
72
+ ### Let the SDK open the editor — `load` / `open`
73
+
74
+ `Office.word.load()` (and `Office.cell.load()`, `Office.show.load()`) creates or reuses the iframe, opens the URL **hidden**, and resolves with the app handle when the document has loaded, so the user never sees the editor boot. `open()` takes the same options and shows the editor from the start.
75
+
76
+ ```ts
77
+ import { Office } from '@thinkfree.dev/tfo-sdk';
78
+
79
+ const word = await Office.word.load({ container: '#editor', url: OPEN_URL }); // hidden until ready
80
+ const body = await word.getDocument().getBody(); // works while hidden
81
+ word.show();
82
+ ```
83
+
84
+ - Pass exactly one of `container` (selector or element; the SDK creates the iframe, sized with `frame`) and `iframe` (an existing element).
85
+ - When `url` has an `app=` parameter it must match the entry point (`Office.word` for Word), otherwise `INVALID_ARGUMENT`.
86
+ - `readyLimitMs` (default 60 s) rejects with `TIMEOUT`; `signal` cancels with `AbortError`. On failure an iframe the SDK created is removed and one you passed in is only made visible again.
87
+ - The app handle adds `show()`, `hide()`, `visible`, `iframe`, and `close()`. `hide()` keeps the size and blocks focus; `close()` disconnects and removes the iframe only if the SDK created it.
88
+
72
89
  ### `createOffice` — low-level factory
73
90
 
74
91
  Use the factory directly when you need `targetWindow` transport or explicit options.
@@ -115,6 +132,20 @@ await doc.getFileName(); // 'report.docx' — current name, inc
115
132
  - Values are not cached. Renames are reflected on every call.
116
133
  - Against an older editor that does not implement the metadata command, these methods (except the synchronous `getApplicationType()`) reject with `SDKError(TIMEOUT)`.
117
134
 
135
+ ### Admin AI provider settings (`getAiProviderConfig`)
136
+
137
+ ```ts
138
+ const config = await app.getAiProviderConfig();
139
+ // { aiProvider: 'openai-compatible', model: 'openai/gpt-5.6-luna', connectionMode: 'relay',
140
+ // relayRequest: { endpoint: 'https://office.example.com/ai-agent/relay', method: 'POST' },
141
+ // openAiCompatible: { preset: 'openrouter' } } — or null when the editor has no admin settings
142
+ ```
143
+
144
+ - The same provider/model the editor's built-in AI assistant uses. Build your relay-mode `aiProviderConfig` from it so a change in the editor's admin page is picked up without touching the host page.
145
+ - Never contains an API key. The relay server keeps the key.
146
+ - Returns `null` when the admin settings are missing or incomplete. Fall back to your own default in that case.
147
+ - Against an older editor that does not implement the command, rejects with `SDKError(TIMEOUT)`.
148
+
118
149
  ## Document handles (`getDocument`)
119
150
 
120
151
  | module | root handle | from the app handle |
@@ -149,9 +180,6 @@ const result = await tools[0].execute({ text: 'Hello' }); // the module's MCP
149
180
  // Frameworks with a registerTool callback (for example the Thinkfree Agent runtime) — register automatically
150
181
  await word.registerTools(modelContext);
151
182
 
152
- // Or dispatch directly (tool names are owned by the module catalog)
153
- await word.execute('insert_text', [{ text: 'Hello' }]);
154
-
155
183
  // System prompt provided by the module ('' when the module has none)
156
184
  const prompt = await word.getSystemPrompt();
157
185
  ```
@@ -163,7 +191,30 @@ In addition to the module catalog, the tool list contains **two SDK-defined tool
163
191
  - `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
192
  - `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
193
 
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.
194
+ ### Office toolkit — tools, prompt and tool results in one object
195
+
196
+ `createOfficeToolkit` packages the catalog, the system prompt and tool execution for your own LLM loop. It converts tools to the wire shape of your provider, appends tool-usage rules to the module prompt, and normalizes every tool result into one **`ToolResult`** shape (`{ success, data?, failure?: { code, message } }`) so the loop can branch on `failure.code` instead of parsing text.
197
+
198
+ ```ts
199
+ import { createOfficeToolkit } from '@thinkfree.dev/tfo-sdk';
200
+
201
+ const toolkit = await createOfficeToolkit(word, { provider: 'openai', preset: 'core' });
202
+
203
+ // toolkit.tools → pass to the LLM request as-is (openai · anthropic · vercel · generic shapes)
204
+ // toolkit.systemPrompt → module prompt + toolkit rules (+ your `prompt.extra`)
205
+ // tool_calls → ToolResult
206
+ const result = await toolkit.dispatch(call.function.name, JSON.parse(call.function.arguments));
207
+ if (!result.success && result.failure.code === 'stale') {
208
+ // the target no longer exists — look it up again before retrying
209
+ }
210
+ ```
211
+
212
+ - **Presets** filter the same catalog: `core` (default, everything but `execute_script`), `review` (read and comment tools only), `full`. Narrow further with `include`.
213
+ - **Failure codes** — `stale` · `no-op` · `capability` · `permission` · `invalid` · `internal`. Transport errors become `internal` failures; only a destroyed connection still throws.
214
+ - **Custom actions** — add partner tools with `customActions` (`partner_*` names — letters, digits, `_`, `-` only, so they satisfy the OpenAI/Anthropic tool-name rule; `run(ctx, args)` or a list of catalog `steps`).
215
+ - `withExecute(toolkit)` returns tools with an `execute` for runtimes that call tools themselves. `dispatchAll` runs a batch in order and stops at the first failure.
216
+
217
+ 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/document-tools-and-error-handling/) 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.
167
218
 
168
219
  ## Error handling
169
220
 
@@ -213,5 +264,5 @@ This package is at 0.x; the public surface may change in minor releases. At runt
213
264
  - Word API: <https://www.developers.thinkfree.com/docs/editor-sdk/word-api/>
214
265
  - Spreadsheet API: <https://www.developers.thinkfree.com/docs/editor-sdk/spreadsheet-api/>
215
266
  - 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/>
267
+ - Document tools and errors: <https://www.developers.thinkfree.com/docs/editor-sdk/document-tools-and-error-handling/>
217
268
  - 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>