esoul-sdk 0.21.1 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 Releases before 0.20.0 are recorded in the repository history only.
 
+## 0.22.0
+
+### Added
+
+- **File transfers: a LIST of files into a workspace folder, as one durable platform job.**
+  `files.transfer({ requestKey?, title?, to: { sourceId: "workspace", path }, items, onConflict?, dedupe? })`
+  → `Transfer` (`snapshot()`, `wait({ timeoutMs })`, `retry({ items? })`, `cancel()`); `getTransfer(id)`,
+  `listTransfers()`. Items are `{ from }` (any readable mount, by ref or address), `{ producer, key }`
+  (the app's own bytes), or `{ staged, name }`; each takes an optional `name` and `subPath`. At most 200
+  items and 100 MB a file. The person sees it in the tasks pane ("Saving 37 files to Mail/Quotes —
+  12/37 · 140 MB of 380 MB") with Stop and Retry. **Retry is clean**: it re-runs only failed and
+  stopped items, pressing it twice is one retry, and a crash at any step followed by a retry leaves
+  exactly what one clean run leaves — no stray bytes, no second file, no second `file_added`, no
+  empty folder the transfer made. Consent is checked when asked (the whole request refused, naming
+  the item) and again as each item runs. See `docs/09-files.md` → "Moving a list of files".
+- **Producers: `fileProducers` in `plugin.json` + `pluginServer.fileProducers[key]`** (`identity(key)`,
+  `open(ctx, key)`, `describe?`) — the app's own bytes (a mail attachment) as a transfer source,
+  opened by the platform inside the item's step, as the app; the bytes never cross an op body.
+  Types: `PluginFileProducer`. Schema: `fileProducers: [{ key, label }]`.
+- **Addresses: `"<sourceId>:/<path>"`** (`"workspace:/Mail/Quotes/a.pdf"`, `"google-drive:/Reports/q3.pdf"`).
+  `read`, `readMany` and the new `stat(addr)` take a ref or an address. `parseFileAddress` (pure).
+- **`files.save(addr, bytes, { onConflict?, key?, contentType? })`** — one file to a path, folders
+  made. **`files.stage({ name, bytes })`** — bytes handed over ahead of a transfer (24 h).
+- **`ctx.files` on a task context** — the same `FilesApi` as `filesForOp(ctx)` (app.tsx cannot import
+  `esoul-sdk/server`).
+- **`useTransfer(transferId)`** in `esoul-sdk/react` — `{ transfer, loading, error, retry(), cancel() }`,
+  polled while it moves and on the platform's nudge; a failed press is named on the failed-request
+  banner with Try again. Works in a Forge preview.
+- **Testing: `memoryFiles` runs transfers and saves on the platform's own protocol** (the same code):
+  `files.producers({...})`, `files.failItem(index, error, { times })`, `files.crashAt(point, { index })`,
+  `transfer.wait()` runs the items in the test, and `files.residue()` →
+  `{ orphanBlobs, duplicateFiles, extraEvents, emptyCreatedFolders }` — assert it is empty after a retry.
+- Pure helpers and types exported from `esoul-sdk`: `TransferRequest`, `TransferSnapshot`,
+  `TransferStatus`, `describeTransferProgress`, `deriveTransferCounts`, `settledTransferStatus`,
+  `pickFreeFileName`, `normaliseTransferPath`, `validateTransferName`, `TRANSFER_*` caps.
+
+### Changed
+
+- **`saveWorkspaceFile` and `importToWorkspace` are idempotent and crash-safe.** They take `key?`
+  and `onConflict?` (`saveWorkspaceFile`). The same key — or, without one, the same bytes and name —
+  into the same folder is the same file (`deduped: true`); a different file with a name already
+  there is saved as `"name (2).ext"` (`renamedFrom`) unless `onConflict` is `"skip"` or `"fail"`.
+  The call throws when its `workspace/file_added` could not be appended (it used to succeed
+  silently with no event), and indexing is started before it returns.
+- In a Forge box, a save or stage through the files door is refused past 3 MB with a sentence
+  (it was an opaque 413 past ≈3.3 MB).
+- Workspace folders in a path walk match case-insensitively, the way `folderPath` makes them.
+
 ## 0.21.1
 
 ### Fixed

package/README.md

@@ -499,7 +499,7 @@ Platform columns on every table: `id`, `workspaceId`, `nodeId`, `ownerId`, `crea
 | `listAppRoles(ctx)` | `{ people, roles, custom, envelope }`. |
 | `defineAppRole(ctx, definition)`, `removeAppRole(ctx, name)` | The owner composes or removes a role inside `roles.custom`. |
 | `getPluginConnectionCredentials(ctx)` | The credentials of the instance's bound connection. |
-| `pluginFiles(ctx)`, `filesForOp(ctx)` | Workspace files and file sources from server code. |
+| `pluginFiles(ctx)`, `filesForOp(ctx)` | Workspace files and file sources from server code: read by ref or address (`"workspace:/Mail/a.pdf"`), `save` to a path, and `transfer` a list of files into a folder with platform progress, Stop and a clean Retry (docs/09). |
 
 ### `esoul-sdk/react`
 
@@ -512,6 +512,7 @@ Platform columns on every table: `id`, `workspaceId`, `nodeId`, `ownerId`, `crea
 | `usePluginRealtime({ channel, workspaceId, nodeId, topics, enabled? })` | Subscribes to the instance's channel. Returns `{ data, latestData, error, state }`. |
 | `useWorkspaceTools(identity)` | Lists and calls tools of other applications from the UI, subject to `workspaceTools`. |
 | `usePluginWorkspaceFiles()`, `usePluginFileUpload()`, `useFileSources()`, `useFileSourceEntries()` | Workspace files, upload, and file sources (workspace, Google Drive, providers). |
+| `useTransfer(transferId)` | A file transfer's progress, with `retry()` and `cancel()`. |
 
 ### `esoul-sdk/testing`