@revoengine/sdk 1.5.8 → 1.6.3

package/README.md

@@ -1,17 +1,17 @@
 # @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`, 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.5.8 compatibility
+## SDK 1.6.3 compatibility
 
 This release synchronizes the complete public SDK contract with the current
 platform low-code declarations. Remote calls require a platform runtime that admits
 the bundled contract revision; publishing the SDK alone does not deploy that runtime.
-Use SDK 1.0.1 with older deployments until their platform contract is upgraded.
+Use the SDK version supported by the target platform deployment until its contract is upgraded.
 
 HTTP Storage requests/responses now use `requestType: 'storage'` and
 `responseType: 'storage'`, with flat Storage-only `source` / `target` objects.
@@ -25,9 +25,29 @@ The `transport` namespace exposes `sftpImport`, `sftpExport`, and `sftpCommands`
 with active Secret names or IDs instead of inline credentials. Storage references
 use the same namespace and effective access rules as other file operations.
 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/build/transport)
+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.3 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
+are removed. Existing integrations should update these calls before rollout.
+
+Database exports can select CSV, TSV, NDJSON, or XLSX. An asynchronous export
+returns its job ID for operation tracking. The import workflow starts with
+`api.importDatabase()`, then permits a reviewed mapping update and an explicit
+`api.commitDatabaseImport()` after preview validation. The generated declarations
+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.
+
 ## Choose your runtime
 
 | Environment | How to start | Authentication |
@@ -35,14 +55,14 @@ for Secret formats and file-transfer examples.
 | 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`, `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`, `agents`, and `execute()` calls | Asynchronous | Asynchronous |
 | Local `utils` and `batch.configure()` | Synchronous unless the utility is inherently asynchronous | Same |
 
 ## Installation
@@ -59,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.5.8 does not
+The platform chooses the hosted package version; publishing SDK 1.6.3 does not
 upgrade existing hosted deployments or their generated package pins.
 
 Hosted user code receives neither a tenant API key nor the private runtime
@@ -78,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'],
@@ -770,3 +790,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 return null in debug/read-only execution. 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.