@verentis/sdk 0.2.6 → 1.0.1

package/README.md

@@ -13,9 +13,9 @@ npm install @verentis/sdk
 ### 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`.
+app token or an API key. The token needs `installation.write` for install, `installation.read` for preview and
+outcomes, plus the Node/Resource installer scopes documented by
+Marketplace. Explicit recovery also needs `installation.write` and `file.delete`.
 
 ```ts
 const preview = await client.installations.preview(invoicingPackageId, {
@@ -56,16 +56,14 @@ const save = client.bridge!.registerAction({
   label: 'Save',
   icon: 'lucide:save',
   variant: 'default',
-  scopes: ['node.file.read', 'node.node.create', 'node.node.update', 'node.journal.create'],
+  scopes: ['file.read', 'file.write'],
   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.update({ id: 'document.save', label: 'Save', scopes: ['file.read', 'file.write'], enabled: true })
 save.dispose()
 ```
 
@@ -171,7 +169,7 @@ 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
+&scope=file.read
 ```
 
 The issued token carries an `act` claim naming the backend client. Add
@@ -221,6 +219,10 @@ const started = await client.executions.run('/scripts/report.py')
 const current = await client.executions.get(started.id)
 const logs = await client.executions.logs(started.id)
 await client.executions.cancel(started.id)
+
+// Scripts that declare their arguments export `<script>.arguments.json`; read it to build a form.
+// Runs never prompt: missing or invalid arguments fail with a validation error.
+const declared = await client.executions.getArguments('/scripts/report.py')   // null when none are declared
 ```
 
 
@@ -293,11 +295,42 @@ contracts must not assume a locally present feature-branch API is already deploy
 | `BridgeAuth` | Auth strategy that receives tokens via the bridge |
 | `matchMimeType` / `findBestMatch` | MIME type matching utilities |
 
+### Chat
+
+`client.chat` is the documented workspace chat API (`/v1/chat`). The caller and workspace always come from the
+token; message content is untrusted Markdown that readers render without raw HTML.
+
+```ts
+const conversation = await client.chat.openDirect({ kind: 'user', id: colleagueId })
+await client.chat.sendText(conversation.id, 'Hi **there**', { idempotencyKey: crypto.randomUUID() })
+
+// Inside the workspace (needs the approved `chat.read` permission): identifier-only live hints over the
+// host's realtime connection. Hints can be lost or repeated, so catch up from durable events.
+const stop = client.chat.subscribeChanges({
+  onChange: async (hint) => {
+    const page = await client.chat.events(hint.conversationId, { afterSeq: lastAppliedSeq })
+    // apply page.items; if page.resetRequired, reload the conversation and its history
+  },
+  onConnection: (status) => { if (status === 'connected') void reconcile() },
+})
+
+// From an installed app's script: post as the app's bot (declared in `spec.chat.bots`). A command script receives
+// chat_conversation_id and chat_invocation_key with its arguments; reusing the key makes a retried run reply once.
+await client.chat.postAsBot({
+  conversationId: params.chat_conversation_id,
+  parts: [{ type: 'text', data: { markdown: 'Invoice 42 needs approval' } }],
+  idempotencyKey: params.chat_invocation_key,
+})
+
+// Run an installed app's slash command as the current user.
+await client.chat.runCommand(conversationId, 'invoicing/approve-invoice', { invoice: 'INV-42' })
+```
+
 ### Workspace settings
 
 Apps whose manifest declares `spec.settings[]` get workspace setting definitions auto-registered
 (namespaced `{manifest-name}.{key}`). Read them with the settings module — the app token needs the
-`fabric.setting.read` / `fabric.setting.read-all` permissions from `spec.permissions`:
+`setting.read` permission from `spec.permissions`:
 
 ```ts
 const settings = client.settings.namespaced('my-app')