@verentis/sdk 0.2.4 → 0.2.5

package/README.md

@@ -10,6 +10,41 @@ npm install @verentis/sdk
 
 ## Quick Start
 
+### Consented Marketplace installation graphs
+
+Installation administration uses a **workspace-bound user token**, not an iframe's delegated
+app token or an API key. The token needs `marketplace.install.create` for preview/install and
+`marketplace.install.read` for outcomes, plus the Node/Resource installer scopes documented by
+Marketplace. Explicit recovery also needs `marketplace.install.update` and `node.file.delete`.
+
+```ts
+const preview = await client.installations.preview(invoicingPackageId, {
+  packageVersion: '1.0.0',
+  branch: 'main',
+})
+// Display ALL preview.packages: publisher, version, treeDigest, permissions,
+// manifestYaml, installMode, branch, installPaths, reuse/recovery IDs.
+// Only after the user explicitly agrees to this exact displayed preview:
+const result = await client.installations.install(preview, true)
+```
+
+`preview()` does not install or grant capability authority. Dependencies use canonical
+`publisher/package-id` identities and exact SemVer pins; optional CRM is never implicit.
+`install()` consumes the exact stored fingerprint once. Stale graphs, changed live package
+content/permissions/signing or withdrawn eligibility are rejected, never silently expanded.
+HTTP failures propagate as the existing `ApiError`, including their response body.
+
+After a failure or lost response, inspect
+`await client.installations.graphResult(preview.operationId)` instead of repeating `install()`.
+The durable result includes the exact package baseline and per-package outcomes/ledger IDs.
+Installation is not atomic: installed/shared dependencies and retained data are not rolled back.
+A Failed exact target needs a **new** preview and explicit recovery consent; uncertain
+Installing/Updating targets require ledger/operator investigation.
+Dependency-free `update()` / `uninstall()` remain available; updates cannot bypass declared
+dependency consent. WOPI, hosted services and transactional email retain their separate
+verified capability-consent flows. A graph checkbox or unsigned Canvas document is not
+signature proof or financial/email authority.
+
 ### Hosted header actions (SDK 0.2)
 
 Applications register buttons after `await client.whenReady()`. The workspace owns their
@@ -53,6 +88,34 @@ Migrated actions are hosted only: there is no legacy-host or standalone-toolbar
 Fullscreen apps can hide the host header only when they register no actions. Keep specialized
 controls (zoom, editing modes, contextual forms) within the app.
 
+### Host messages (agent → open app)
+
+An agent acting for the user can send structured messages to an app the user has open (the
+`app_send_message` AI tool). Declare each channel in the manifest so agents can discover it and the
+host forwards nothing else:
+
+```yaml
+spec:
+  messages:
+    - channel: select-record        # ^[a-z0-9][a-z0-9._-]{0,63}$
+      description: Selects a CRM record by id.
+      schema: { type: object, properties: { id: { type: string } }, required: [id] }
+```
+
+```ts
+const stop = client.bridge!.onHostMessage('select-record', async (payload) => {
+  const { id } = payload as { id: string }
+  await selectRecord(id)
+  return { selected: id }        // the reply the agent receives (keep it small JSON)
+})
+```
+
+Treat payloads as untrusted input and validate them against your schema. Throw to report a
+failure. The protocol uses session-bound `verentis:host:message` / `verentis:host:reply` messages
+with a correlation `requestId`; replays are ignored and undeclared or unhandled channels get an error
+reply. Messages are only delivered while the user has "Follow agent" on or accepts the suggestion,
+and the host waits about 15 seconds for a reply.
+
 Release the 0.2 SDK before deploying apps that require `^0.2.0`, together with the matching host.
 Local sibling-repository development can link the built SDK; published applications must resolve
 the released SDK from npm.
@@ -77,9 +140,44 @@ control IDs from authenticated `/derived`; it does not reconstruct a launch,
 including after signing-key rotation. Keep the initial launch/form separate from
 active document metadata, retain CODE's iframe and existing token, and preserve
 unverified edits until a matching target save receipt arrives.
-These methods do not replace `requestBackendCredential()` or ordinary OAuth
-authentication for apps that need workspace APIs. WOPI-only packages need no
-per-editor OAuth client secret.
+These methods do not replace ordinary OAuth authentication for apps whose
+backend needs workspace APIs. WOPI-only packages need no per-editor OAuth
+client secret.
+
+### App backends (OAuth 2.0 Token Exchange)
+
+An installed app's backend is an ordinary confidential OAuth client. The iframe
+forwards the user's current, file-scoped access token to its own backend; the
+backend exchanges it on behalf of the user (RFC 8693) at Security's token
+endpoint. The installation's approved permissions are the consent: the exchange
+is refused for a backend client the workspace has not approved, and it can
+never widen the user's scopes or resource.
+
+```ts
+// iframe
+const authorization = await client.getAuthorizationHeader()
+await fetch('https://backend.example.com/convert', {
+  method: 'POST',
+  headers: { Authorization: authorization! },
+  body: JSON.stringify({ nodeId: client.context.file?.nodeId }),
+})
+```
+
+```http
+POST /connect/token
+Authorization: Basic base64(client_id:client_secret)
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:ietf:params:oauth:grant-type:token-exchange
+&subject_token=<forwarded access token>
+&subject_token_type=urn:ietf:params:oauth:token-type:access_token
+&scope=node.file.read
+```
+
+The issued token carries an `act` claim naming the backend client. Add
+`offline_access` (or `requested_token_type=urn:ietf:params:oauth:token-type:refresh_token`)
+when the backend must keep working after the user leaves; every refresh is
+re-authorized against the installation's live consent.
 
 ### Standalone mode (local development)
 
@@ -150,6 +248,36 @@ credentials and `workspaceId` yourself.
 
 ## API Overview
 
+### Revision-safe node content
+
+Use stable node IDs and an explicit branch for editing existing records. Read bytes and their
+strong revision together; submit that revision and a caller-owned idempotency key when saving:
+
+```ts
+const snapshot = await client.files.readNodeContent(nodeId, { branch: 'main' })
+const next = await client.files.writeNodeContent(nodeId, {
+  branch: 'main',
+  revision: snapshot.revision,
+  idempotencyKey: crypto.randomUUID(),
+  content: editedJson,
+})
+```
+
+`getNode(nodeId, { branch })` returns stable metadata, including its unquoted `etag`, which
+`writeNodeContent` also accepts. Node-content writes replace bytes only; they do not create files,
+move paths or change MIME types. Keep the same revision, bytes and operation key for an identical
+retry; a new edit needs a new key. The SDK does not automatically retry or report a stale save as
+successful. `ApiError` is a runtime export and exposes `status`, `detail`, optional `title` and the
+platform's optional machine-readable `code` (for example `revision_mismatch`).
+
+Path deletion uses `remove({ path, branch, headStamp?, idempotencyKey?, mode? })` with the routed
+file API. `headStamp` is a **path-binding head stamp**, not the quoted node-content revision.
+The default mode is shallow; request `deep` explicitly for recursive deletion. These options
+do not bypass server authorization or mutation guards and do not introduce financial transactions.
+
+Deploy only with a platform release providing the conditional node-content routes. New app
+contracts must not assume a locally present feature-branch API is already deployed.
+
 | Export | Description |
 | --- | --- |
 | `createVerentisClient(options?)` | Factory function — creates a configured `VerentisClient` |
@@ -202,15 +330,14 @@ npm run typecheck
 
 ## Versioning
 
-This project uses [GitVersion](https://gitversion.net/) for automatic semantic versioning:
+The release workflow publishes the exact stable version in `package.json` after changes
+merge to `main`. Update both `package.json` and `package-lock.json` when preparing a new
+version; npm versions are immutable.
 
-- Commits to `main` produce clean versions (e.g., `0.1.1`, `0.1.2`)
-- Feature branches produce pre-release versions (e.g., `0.2.0-my-feature.1`)
-- Use commit message tags to control version bumps:
-  - `+semver: breaking` or `+semver: major` — major bump
-  - `+semver: feature` or `+semver: minor` — minor bump
-  - `+semver: fix` or `+semver: patch` — patch bump (default)
-  - `+semver: none` or `+semver: skip` — no bump
+A version older than the current npm `latest` is published under `version-<version>`
+without moving `latest` backwards. Consumers of such a release must install its exact
+version (for example, `npm install @verentis/sdk@0.2.0 --save-exact`), not a caret range
+that can resolve to a different release.
 
 ## License