@thinkfree.dev/tfo-sdk 0.2.1 → 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 +10 -7
- package/dist/apiReference.generated.js +19572 -0
- package/dist/apiReference.generated.js.map +1 -0
- package/dist/index.d.ts +2268 -986
- package/dist/index.js +870 -42
- package/dist/index.js.map +1 -1
- package/dist/sdk-api-doc.html +11889 -8003
- package/dist/sdk-api-doc.ko.md +4201 -0
- package/dist/sdk-api-doc.md +2880 -2377
- package/dist/version.json +4 -4
- package/package.json +3 -4
- package/dist/sdk-api-catalog.json +0 -9076
package/README.md
CHANGED
|
@@ -108,13 +108,11 @@ await app.getApplicationName(); // 'Word Processor' — display name
|
|
|
108
108
|
await app.getApplicationVersion(); // 'V17.0.0' — editor server build (null when the deployment does not expose it)
|
|
109
109
|
|
|
110
110
|
const doc = app.getDocument();
|
|
111
|
-
await doc.isReadOnly(); // reflects the mode the document actually opened in
|
|
112
111
|
await doc.getFileName(); // 'report.docx' — current name, including renames
|
|
113
112
|
```
|
|
114
113
|
|
|
115
114
|
- `getApplicationVersion()` (editor server build, async) and `getVersion()` (SDK bundle, sync) are different values.
|
|
116
|
-
-
|
|
117
|
-
- Values are not cached. Renames and mode changes are reflected on every call.
|
|
115
|
+
- Values are not cached. Renames are reflected on every call.
|
|
118
116
|
- Against an older editor that does not implement the metadata command, these methods (except the synchronous `getApplicationType()`) reject with `SDKError(TIMEOUT)`.
|
|
119
117
|
|
|
120
118
|
## Document handles (`getDocument`)
|
|
@@ -127,11 +125,15 @@ await doc.getFileName(); // 'report.docx' — current name, inc
|
|
|
127
125
|
|
|
128
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).
|
|
129
127
|
|
|
130
|
-
All root handles share the module-independent
|
|
128
|
+
All root handles share the module-independent method `getFileName()` described above.
|
|
131
129
|
|
|
132
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.
|
|
133
131
|
|
|
134
|
-
|
|
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.
|
|
135
137
|
|
|
136
138
|
## AI agent integration
|
|
137
139
|
|
|
@@ -171,8 +173,9 @@ Failures reject with `SDKError`. When a document handle call fails, `SDKError.da
|
|
|
171
173
|
import { SDKError, type ApiErrorResponse } from '@thinkfree.dev/tfo-sdk';
|
|
172
174
|
|
|
173
175
|
try {
|
|
174
|
-
const ws = wb.getWorksheet('Nope');
|
|
175
|
-
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();
|
|
176
179
|
} catch (e) {
|
|
177
180
|
if (e instanceof SDKError && e.data && typeof e.data === 'object') {
|
|
178
181
|
const { error } = e.data as ApiErrorResponse;
|