@revoengine/sdk 1.6.2 → 1.6.4

package/README.md

@@ -1,12 +1,12 @@
 # @revoengine/sdk
 
 Official Node.js SDK for RevoEngine. It provides the modern `api`, `utils`,
-`storage`, `transport`, and `agents` namespaces, top-level `execute()`, and the `batch` controller in both
+`storage`, `transport`, `vault`, `serviceAccount`, and `agents` namespaces, top-level `execute()`, and the `batch` controller in both
 Revo-hosted `CUSTOM_NODEJS` components and standalone Node.js applications.
 
 Requirements: Node.js 22 or newer.
 
-## SDK 1.6.2 compatibility
+## SDK 1.6.4 compatibility
 
 This release synchronizes the complete public SDK contract with the current
 platform low-code declarations. Remote calls require a platform runtime that admits
@@ -28,7 +28,7 @@ Legacy SFTP helpers and the removed thread-goal methods are not exposed by the
 current SDK contract. Refer to the [transfer guide](https://docs.revoengine.com/low-code/sftp)
 for Secret formats and file-transfer examples.
 
-SDK 1.6.2 retains portable Component digest declarations and one readable-relation
+SDK 1.6.4 retains portable Component digest declarations and one readable-relation
 contract for Databases, live Views, and Materialized Views. Use `api.exportDatabase()`
 for all three relation types. `api.getDatabaseViewData()` remains a deprecated
 read alias; `api.exportDatabaseView()` and separate REST View export operations
@@ -41,6 +41,9 @@ returns its job ID for operation tracking. The import workflow starts with
 describe the current request and response shapes; the platform still enforces
 permissions and validates source and target state before committing an import.
 
+Assistant model inputs follow the current platform: `gpt-6.1-sol` and
+`gpt-6-luna`; Fast mode is supported for Luna. Update older Sol model identifiers.
+
 Remote MCP server configurations in this contract use public HTTPS destinations.
 Private-network access is not an accepted SDK setting; review the server URL,
 provider consent, Vault binding, and tool permissions before enabling a plugin.
@@ -52,14 +55,14 @@ provider consent, Vault binding, and tool permissions before enabling a plugin.
 | Revo-hosted `CUSTOM_NODEJS` | Export `async function init(runtime)` | Revo injects an execution-bound runtime; user code receives no API key. |
 | Standalone Node.js | Create `new RevoClient(options)` | Supply a RevoEngine API key explicitly or through an environment variable. |
 
-Both modes expose the same `api`, `utils`, `storage`, `transport`, `agents`, `execute`, and `batch`
+Both modes expose the same `api`, `utils`, `storage`, `transport`, `vault`, `serviceAccount`, `agents`, `execute`, and `batch`
 properties, but return types reflect where the work happens:
 
 | Call kind | Revo-hosted | Standalone |
 | --- | --- | --- |
 | Execution snapshot, cache, debug, and logging | Synchronous | Throws synchronously because no execution context exists |
 | Current user and instance | Synchronous injected snapshot | Asynchronous lazy `/api/v1/me` discovery |
-| Remote `api`, `storage`, `agents`, and `execute()` calls | Asynchronous | Asynchronous |
+| Remote `api`, `storage`, `transport`, `vault`, `serviceAccount`, `agents`, and `execute()` calls | Asynchronous | Asynchronous |
 | Local `utils` and `batch.configure()` | Synchronous unless the utility is inherently asynchronous | Same |
 
 ## Installation
@@ -76,7 +79,7 @@ RevoEngine pins that version again in the deployment package and injects the
 runtime into the component entrypoint. Component code does not construct a
 `RevoClient`.
 
-The platform chooses the hosted package version; publishing SDK 1.6.2 does not
+The platform chooses the hosted package version; publishing SDK 1.6.4 does not
 upgrade existing hosted deployments or their generated package pins.
 
 Hosted user code receives neither a tenant API key nor the private runtime
@@ -95,7 +98,7 @@ separate initialization method.
 ```js
 /** @param {import('@revoengine/sdk').RevoRuntime} runtime */
 export async function init(runtime) {
-  const { api, utils, storage, agents, execute, batch } = runtime;
+  const { api, utils, storage, vault, agents, execute, batch } = runtime;
   const { data: rows, next } = await api.getDatabaseData('Sales', {
     fields: ['saleId', 'customerId', 'total', 'createdAt'],
     sort: ['-createdAt'],
@@ -153,6 +156,8 @@ Execution-only methods such as `api.input()`, `api.getContext()`,
 `api.getExecutionId()`, and `api.getOperationId()` are available only in hosted
 executions.
 
+Use `runtime.execute(code, { readOnly: true })` for transient code that must not write platform state. `readOnly: false` selects full execution for an authorized standalone client; a hosted execution inherits its mode and cannot escalate a restricted parent.
+
 ### Configure hosted batching
 
 Configure batching before the first remote call:
@@ -787,3 +792,85 @@ Common subclasses include:
 - Deprecated low-code methods and aliases are excluded.
 - `api.transactionDatabaseData` is excluded.
 - Runtime batches are non-transactional and are not retried automatically.
+
+## Vault manager
+
+The native `client.vault` manager uses the same get/create/update/delete/rotate
+contract for instance (default) and verified user scope. Get alone returns
+`secret.revision.value` as a Buffer containing the stored UTF-8 text; Rotate returns metadata without values.
+Revision versions are normalized validFrom timestamps. validFrom accepts null,
+Date, ISO or epoch milliseconds; a future Rotate preserves current availability.
+`listRevisions` exposes paginated metadata history.
+
+```ts
+const secret = await client.vault.get('TOKEN', { scope: 'user' });
+const token = secret.revision.value.toString('utf8');
+await client.vault.rotate('TOKEN', { value: replacement }, { scope: 'user', validFrom: null });
+```
+
+Do not log values or access tokens. Instance access requires Secret roles and
+creator ownership or administrator rights. User scope uses the verified account;
+management requires owner rights and does not inherit saved Component/Tool grants.
+Writes throw `READ_ONLY_OPERATION_FORBIDDEN` when the execution has `readOnly: true`. See the
+[Vault guide](https://docs.revoengine.com/low-code/reference/vault) for all methods.
+
+The same flat manager exposes `getAccessToken`, `getIntegrationMetadata`,
+`discoverIntegration`, `connectIntegration`, and `disconnectIntegration`. Token reads
+return the access token with its matching ISO expiry and refresh when necessary.
+Connect requires nullable `expectedRevision` (null to create) and returns an
+authorization URL for interactive consent through the existing frontend callback.
+Disconnect retains definition/history/grants and does not revoke provider access.
+Saved Component/Tool reads preserve exact personal grants; direct SDK owner/admin
+reads and management are authorized separately.
+
+
+## Bulk Jobs and Webhooks
+
+Use `api.cancelJobs`, `retryJobs`, `deleteJobs`, `cancelWebhooks`, `retryWebhooks`,
+and `deleteWebhooks` with exactly one non-empty platform `filter` or an ID array
+(`jobIds` / `webhookIds`, 1–1000 IDs). A filter selects every matching row beyond
+list pagination. An optional actor-scoped `idempotencyKey` protects repeat admission.
+The SDK never automatically retries mutations.
+
+```ts
+const input = {
+  filter: { field: 'status', op: 'eq', value: 'ERROR' },
+  idempotencyKey: 'retry-errors-2026-10-01',
+};
+const preview = await client.api.previewAutomationOperation('jobs', 'retry', input);
+// Review advisory preview.matched / preview.eligible before submitting.
+const operation = await client.api.retryJobs(input);
+const progress = await client.api.getAutomationOperation(operation.operationId);
+const outcomes = await client.api.getAutomationOperationItems(operation.operationId);
+// Fetch subsequent pages with outcomes.nextCursor as the second argument.
+```
+
+Operations report `PENDING`, `PROCESSING`, `FINISHED`, or `ERROR`, plus
+`total`, `processed`, `skipped`, and `failed`. `FINISHED` means lifecycle requests
+were processed; downstream execution/delivery may continue and failed can be non-zero.
+Item pages contain safe source/result IDs and error codes. Preview is advisory;
+admission freezes selection and the worker rechecks state and permissions.
+Cancel/delete require Automation Admin; retry accepts Automation Runner/Admin.
+
+`retryWebhooks` accepts `requestPatch`: url/method/body replace whole fields;
+headers/query accept `set` and `remove`, and `maskDetails` adds masks while preserving
+existing masks. Masked original values cannot be recovered: provide explicit
+replacements or the item fails with `REPLAY_PAYLOAD_UNAVAILABLE`. If the entire
+headers section was masked, `headers.set` supplies its complete replacement.
+Request patches are limited to 1 MiB of serialized JSON. Never log replacement
+credentials. The operation result does not expose saved request bodies.
+
+```ts
+await client.api.retryWebhooks({
+  webhookIds: selectedWebhookIds,
+  idempotencyKey: retryAdmissionKey,
+  requestPatch: {
+    headers: { set: { Authorization: `Bearer ${replacementToken}` }, remove: ['X-Old-Key'] },
+    query: { set: { apiVersion: '2' }, remove: ['legacy'] },
+    maskDetails: ['headers.Authorization'],
+  },
+});
+```
+
+The target platform requires the bulk-operation migration and an active API worker
+lane. Publishing this SDK does not deploy them or change the hosted SDK pin.