esoul-sdk 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 Releases before 0.20.0 are recorded in the repository history only.
 
+## 0.25.0
+
+### Added
+
+- Credential slots for ANY provider (docs/08): `family: "oauth2"` (any OAuth 2.0 provider —
+  Microsoft for Outlook / OneNote / OneDrive, Dropbox, GitHub… — with `provider: { name,
+  authorizeUrl, tokenUrl, scopes, hosts }`) and `family: "apiKey"` (a key the person pastes, with
+  `provider: { name, hosts, header?, prefix?, verifyUrl? }`), beside `google`. The person connects
+  the account once in Account settings → Accounts (their own registered OAuth client, entered once
+  and sealed, or one the platform holds for the app), assigns it to apps like a Google account, and
+  your code calls `credentials(ctx).slot(name).fetch(url)`: the platform adds the token or key and
+  sends it only to the declared hosts the person approved. The token, the refresh token, the key and
+  the client secret never reach app code. Each app's calls get a token narrowed to its own scopes
+  when one account serves several apps; a `connectUrl` opens Account settings → Accounts (nothing
+  signs in from a link); an account the provider does not name is refused (declare `accountUrl`
+  or ask for `openid`); "the same provider" means the same `authorizeUrl` and `tokenUrl`.
+- `CredentialStatus.provider` (`{ name, family }`) and `missingHosts`; `useCredential` and
+  `<ConnectAccount/>` word themselves with the provider's name.
+- `fakeCredentials(slots)` (esoul-sdk/testing): test code that uses an account, with the platform's
+  refusals and every call recorded.
+- Manifest exports: `OAuth2ProviderSchema`, `ApiKeyProviderSchema`, `GoogleCredentialSlotSchema`,
+  `OAuth2CredentialSlotSchema`, `ApiKeyCredentialSlotSchema`, `CREDENTIAL_HOST_RE`,
+  `RESERVED_AUTHORIZE_PARAMS`, `credentialProviderKey`.
+
+### Changed
+
+- `getPluginConnectionCredentials` (the older `connections`) answers only inside the app's own
+  running op, route or task, and only for a connection of the owner of the workspace the call runs
+  in. Prefer a credential slot (docs/08 §9).
+
+## 0.24.0
+
+### Added
+
+- `questions(ctx)` (esoul-sdk/server): a question your app needs the person to answer reaches the
+  platform's questions bell on every workspace — options as buttons, an Open button that lands on
+  the place inside your app (`useAppNav`), and the answer delivered to your own op as the person who
+  answered. `settle(key, …)` closes it when your own screen took the answer (docs/06-server.md,
+  "Asking the person").
+- `mailWaitDirective(runCtx, …)`: an app tool pauses an agent network run until mail arrives at this
+  inbox on a thread or from a sender — the platform's own wait kernel (docs/04-tools.md, "Waiting
+  inside a network run").
+
 ## 0.23.0
 
 ### Added

package/README.md

@@ -16,7 +16,11 @@ platform's implementations.
 - [Getting started](docs/01-getting-started.md)
 - [Manifest reference](docs/02-manifest.md)
 - [Documentation index](#documentation)
+- [A service on your computer, connected to your app](docs/20-a-service-on-your-computer.md)
+- [CHANGELOG.md](CHANGELOG.md) — what each version added
+- `api-reference.md` — every export with its signature and doc comment
 - `llms.txt` and `llms-full.txt` — the documentation in one file, for coding models
+- The package on npm: <https://www.npmjs.com/package/esoul-sdk>
 
 ## Features
 
@@ -80,7 +84,8 @@ test helpers. Functions that need the platform (`pluginDb`, `viewerProfile`, `mi
 throw `host only` when called outside it; they are exercised through the test harness or in a
 Forge workbench.
 
-Requirements: Node.js 20 or newer, TypeScript 5, React 19 for the UI entry point.
+Requirements: Node.js 20 or newer (22 for `esoul-device` on a computer), TypeScript 5, React 18 or
+newer for the UI entry point.
 
 ## Concepts
 
@@ -120,11 +125,13 @@ application that provides the named contract.
 | Import | Contents |
 |---|---|
 | `esoul-sdk` | Schema and event types, `defineOps`, `handleOp`, `opTool`, `definePluginChannel`, `defineBindingEvent`, `checkBinding`, `resolveAppRole`, `chartSvg`, `incompleteStateNotice`, `deterministicReducerId`, `callPluginOp`, `kickPluginTask`, `pluginRouteUrl`, `nanoid`, the manifest schema, `compileEnvelope`, `compileCustomRole` |
-| `esoul-sdk/server` | `pluginDb`, `viewerProfile`, `sseStream`, `mintRouteToken`, `readAppState`, `callWorkspaceTool`, `computer`, `emitPluginAppEvent`, `generateAppImage`, `renderChartImage`, `setAppRole`, `listAppRoles`, `defineAppRole`, `removeAppRole`, `getPluginConnectionCredentials`, `pluginFiles`, and the context types (`PluginOpContext`, `PluginRouteContext`, `PluginViewer`, `PluginServerModule`) |
-| `esoul-sdk/react` | `useViewer`, `useSignInWall`, `useAppCanEdit`, `usePluginEventDispatch`, `usePluginRealtime`, `useWorkspaceTools`, `usePluginWorkspaceFiles`, `usePluginFileUpload`, `useFileSources`, `useFileSourceEntries`; the types `PluginViewerPublic`, `SignInWall` |
-| `esoul-sdk/testing` | `memoryDb`, `fakeViewer`, `runOp`, `fakeApps`, `capture`, `startMockOAuth` |
+| `esoul-sdk/server` | `pluginDb`, `viewerProfile`, `sseStream`, `mintRouteToken`, `readAppState`, `callWorkspaceTool`, `computer`, `devices`, `questions`, `credentials`, `llm`, `filesForOp`, `pluginFiles`, `emitPluginAppEvent`, `generateAppImage`, `renderChartImage`, `setAppRole`, `listAppRoles`, `defineAppRole`, `removeAppRole`, `getPluginConnectionCredentials`, and the context types (`PluginOpContext`, `PluginRouteContext`, `PluginViewer`, `PluginServerModule`) |
+| `esoul-sdk/react` | `useViewer`, `useSignInWall`, `useAppCanEdit`, `usePluginEventDispatch`, `runOptimistic`, `useAppNav`, `usePluginRealtime`, `useWorkspaceTools`, `useRemoteReconcile`, `useCredential`, `<ConnectAccount/>`, `<ConnectComputer/>`, `useDevices`, `useDeviceRun`, `useDeviceActions`, the file hooks (`useFileSources`, `useFileSourceEntries`, `useFolderAutocomplete`, `useFileUrls`, `useTransfer`, `usePluginWorkspaceFiles`, `usePluginFileUpload`), `ImageLabeler`; the types `PluginViewerPublic`, `SignInWall` |
+| `esoul-sdk/machine` | what runs ON the person's computer: the `Program` type for a device program (types only), and the `esoul-device` runtime |
+| `esoul-sdk/testing` | `memoryDb`, `fakeViewer`, `runOp`, `fakeApps`, `capture`, `memoryFiles`, `scriptedModel`, `simGmail`, `fakeCredentials`, `startMockOAuth`, `listFailedRequests` |
 | `esoul-sdk/schemas/plugin.schema.json` | The JSON Schema of the manifest |
 | `esoul-app validate <dir>` | Command-line validator for a package folder |
+| `esoul-device` | The runtime on a person's computer: `connect`, `status`, `sh`, `config set`, `disconnect`, `uninstall` (docs/18) |
 
 ## Getting started
 
@@ -498,7 +505,8 @@ Platform columns on every table: `id`, `workspaceId`, `nodeId`, `ownerId`, `crea
 | `setAppRole(ctx, { email, role, attrs? })` | The owner gives an account one of the application's role words, or a composed role, with attribute values (`{ customer: "204" }`) validated against `roles.attributes`. Recorded as an event. |
 | `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. |
+| `credentials(ctx).slot(name)` | The person's account for a declared slot — Google, any OAuth 2.0 provider (Microsoft, Dropbox…) or a pasted API key: `status()` and `fetch(url, init?)`, with the token or key added by the platform and sent only where the slot may reach. Your code never holds it (docs/08). |
+| `getPluginConnectionCredentials(connectionId, pluginId)` | Older: the token of one of the app's own `connections`, readable only from the app's own running call for the workspace owner's connection. Prefer a `credentials` slot (docs/08 §9). |
 | `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`
@@ -523,6 +531,7 @@ Platform columns on every table: `id`, `workspaceId`, `nodeId`, `ownerId`, `crea
 | `runOp(server, opName, { viewer, args?, db?, apps?, notifyFails? })` | Calls `pluginServer.ops[opName]` with a platform-shaped context. Returns `{ result, notified, emitted }`; throws the op's refusals. |
 | `fakeApps(fixtures)` | Bound applications for `ctx.apps`. |
 | `capture()` | A recorder for callbacks. |
+| `fakeCredentials(slots)` | A stand-in for `credentials(ctx)`: each slot answers as the test says (`status`, `hosts`, `fetch`), the platform's refusals apply, and `calls` records every request (docs/08 §7). |
 | `startMockOAuth(opts?)` | A local OAuth server for connection tests. |
 
 ### Command line
@@ -565,7 +574,7 @@ Exits 0 when the folder is a well-formed application package; otherwise prints e
 | [5. The UI](docs/05-ui.md) | React, hooks, theme, responsive rules |
 | [6. The server](docs/06-server.md) | Ops, routes, webhooks, `computer`, charts, calling other applications |
 | [7. Background tasks](docs/07-background-tasks.md) | The durable executor, the replay model, concurrency |
-| [8. Connections](docs/08-connections.md) | OAuth and API-key connections held by the platform |
+| [8. Accounts](docs/08-connections.md) | The person's Google, Microsoft or any OAuth 2.0 / API-key account, used through the platform without your code holding the token |
 | [9. Files](docs/09-files.md) | Workspace files, Drive, file providers |
 | [10. Testing](docs/10-testing.md) | The fold contract, ops, tasks and rules as tests |
 | [11. Shipping](docs/11-shipping.md) | The repository, review, release, install, dependencies |
@@ -574,12 +583,20 @@ Exits 0 when the folder is a well-formed application package; otherwise prints e
 | [14. Your own tables](docs/14-database.md) | `db`, rules, scopes, sealed fields, indexes, migrations |
 | [15. Realtime](docs/15-realtime.md) | Topics, audiences, addressing |
 | [16. Bindings](docs/16-bindings.md) | Slots, contracts, reaching another application |
+| [17. Editing and merging](docs/17-editing-and-merging.md) | An editor that takes changes from other devices and agents; merges |
+| [18. Your computer](docs/18-your-computer.md) | The device arm: commands, the workspace, programs, `esoul-device` |
 | [19. Model calls](docs/19-model-calls.md) | `llm(ctx)`: billed model calls, budgets, `scriptedModel()` for tests |
+| [20. A service on your computer](docs/20-a-service-on-your-computer.md) | A walk-through: a program that keeps a service running on the person's computer, talking to the app both ways — built in the Forge, then installed |
 
 ## Versions
 
+From 0.20.0 on, every version is in [CHANGELOG.md](CHANGELOG.md) (accounts through the platform — Google, then any OAuth 2.0 or API-key provider in 0.25.0,
+model calls, file transfers, opened-from-outside navigation, server-only events, the questions bell,
+mail waits). Earlier:
+
 | Version | Changes |
 |---|---|
+| 0.16.0 – 0.19.1 | `runOptimistic` and the failed-request banner; stable list paging; editor sync (`useRemoteReconcile`, `mergeLines` / `mergeFields` / `mergeRecordsById`); the device arm — `devices(ctx)`, `<ConnectComputer/>`, the `esoul-device` runtime, declared commands, the shared command line, an app's own program on the computer (docs/17, 18). |
 | 0.15.0 | **Files work in a Forge box**, and do more: `FilesApi.list(…, opts)` narrowed at the source, `listAll`, `resolvePath`, `readMany`, `write` (make or replace by name — a label file beside its image; manifest `fileSources.write`), `readGrant` + `fileGrantUrl` (signed, expiring URLs for an `<img>` in a preview and for a machine). UI: `useFolderAutocomplete`, `useFileUrls`, `useFileSourceEntries(…, opts)` with `loadMore`, `listFileEntries`, `resolveFilePath`. `ImageLabeler` / `PolygonCanvas` — the Explorer's polygon editor as a component. Pure: `pairImagesWithLabels`, `serializeLabelMe`, `parseLabelMe`, `labelFileNameFor`. Testing: `memoryFiles`. |
 | 0.14.0 | Attribute-scoped access: `roles.attributes` (typed; validated when granted; `viewer.attrs`); scoped rule principals `{ role, where }` with `viewer.<attribute>`, applied to reads, aggregates, updates and deletes and filling or refusing creates, in both database clients; a rule combining `creator` with a scoped role is refused. `compileManifestRules` is the one reader of a manifest's rules. VIEW AS personas carry attributes (`visitor-a?customer=204`). |
 | 0.13.0 | Composed roles: `roles.custom` envelope; `defineAppRole`, `removeAppRole`; `setAppRole` with attributes; `listAppRoles` returns composed roles and the envelope. Reads, updates and deletes are narrowed by the composition in both database clients; surfaces not handed to the role are refused; `useViewer().customRole` and `can`. `access: [<roles>]` on a surface. Composed roles are personas in the Forge. |