@verentis/sdk 0.1.1 → 0.2.0

package/README.md

@@ -10,6 +10,112 @@ 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
+presentation; handlers execute inside the application with its existing delegated token.
+
+```ts
+const save = client.bridge!.registerAction({
+  id: 'document.save',
+  label: 'Save',
+  icon: 'lucide:save',
+  variant: 'default',
+  scopes: ['node.file.read', 'node.node.create', 'node.node.update', 'node.journal.create'],
+  enabled: false,
+}, async () => {
+  await persistDocument()
+})
+
+// Pass the complete descriptor when document state changes.
+save.update({ id: 'document.save', label: 'Save', scopes: [
+  'node.file.read', 'node.node.create', 'node.node.update', 'node.journal.create',
+], enabled: true })
+save.dispose()
+```
+
+Use stable app-local IDs, up to 16 actions, Lucide icon identifiers, and explicit `scopes`
+(`[]` for client-only operations). `enabled`, `visible`, `busy`, and `disabledReason` communicate
+state without serializing handlers. The host checks required scopes against the delegated grant;
+registration never expands permissions. Throw on failure so the host can display it.
+
+For clipboard actions, set `kind: 'clipboard'` and return `{ clipboardText: source }`. The host starts
+the clipboard write in the user's click gesture while awaiting the text, preserving browser
+user-activation requirements. For operations that navigate after completion, return
+`{ navigate: { path: '/applications', newTab: false } }` instead of navigating before the result.
+
+The protocol uses session-bound `verentis:actions:set`, `verentis:action:invoke`, and
+`verentis:action:result` messages. Reload/navigation disposes pending work; an unanswered invocation
+times out as **outcome unknown**, never an automatic retry. App handlers must not report successful
+completion before their mutation finishes.
+
+Migrated actions are hosted only: there is no legacy-host or standalone-toolbar fallback.
+Fullscreen apps can hide the host header only when they register no actions. Keep specialized
+controls (zoom, editing modes, contextual forms) within the app.
+
+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.
+
+### WOPI editor launch
+
+Signed WOPI applications use `Bridge.requestWopiLaunch()` after `waitForInit()`.
+The authenticated workspace parent chooses the installed editor, document,
+branch and action; the child cannot request arbitrary document identities.
+The returned token is scoped to WOPI and is not a normal workspace API token.
+Submit it using a form POST to the validated discovery action, never a URL.
+
+`requestWopiSave(generation)`, `getWopiStatus()` and `closeWopiSession()` use the
+same exact-parent, origin/session/request-correlated bridge. A matching durable
+save receipt—not a CODE postMessage alone—is required before clearing dirty state.
+When status reports `continuationAvailable`, `requestWopiContinuation()` asks
+the parent to bind the target of a completed server-owned Save As operation.
+It accepts no document or acquisition IDs. Its `WopiContinuation` result contains
+only document metadata and the persisted target `accessTokenTtl`, not a token,
+action URL or private control credential. The parent obtains the exact existing
+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.
+
 ### Standalone mode (local development)
 
 ```ts
@@ -79,6 +185,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` |
@@ -131,15 +267,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