@revoengine/sdk 2.0.0 → 4.0.0

package/README.md

@@ -1,17 +1,34 @@
 # @revoengine/sdk
 
 Official Node.js SDK for RevoEngine. It provides the modern `api`, `utils`,
-`storage`, 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 2.0.0 compatibility
+Development and GitLab CI use Node.js 24.21.0. Run `nvm use` to select the checked-in `.nvmrc`.
 
-This major release synchronizes the complete public SDK contract with the current
-platform low-code declarations. Remote calls require a platform runtime that admits
+## SDK 4.0.0 compatibility
+
+SDK 4.0.0 targets RevoEngine 1.8.0. Remove `skipLibs`, `includeLibs` and
+`excludeLibs` from execution configuration; libraries are resolved automatically.
+These names remain valid as ordinary business data outside those configuration
+locations. Upgrade the SDK and target platform together; use SDK 3.0.0 for an
+instance that still runs 1.7.1. Follow the
+[1.8 upgrade guide](https://docs.revoengine.com/developers/upgrading-to-1-8).
+
+## Earlier SDK 3.0.0 migration
+
+This major release synchronizes the complete public SDK contract with RevoEngine
+1.7.1 and removes deprecated compatibility methods and legacy Files types. 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.
+
+Storage declarations include physical-line reads, quote-disabled CSV dialects,
+per-record byte limits, and the opt-in `onError: 'skipRow'` read policy. That policy
+skips records with the wrong source column count and returns bounded locations in
+`csvReport`; syntax and record-size errors still abort. The report describes the
+whole source and must not be summed across pages.
 
 HTTP Storage requests/responses now use `requestType: 'storage'` and
 `responseType: 'storage'`, with flat Storage-only `source` / `target` objects.
@@ -21,6 +38,42 @@ network or hosted bridge dispatch. Automation schedules use `{ scheduleFor }`
 options instead of positional dates. Regenerated types also include the current
 Storage and database contracts; use those declarations when migrating callers.
 
+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/low-code/sftp)
+for Secret formats and file-transfer examples.
+
+This release 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, and `api.getDatabaseData()` for structured reads.
+Account data uses `metadata` and `metadataAdvanced`; use `vault.get()` for Secret
+values and `storage.*` for file content. The instance-data source list excludes
+legacy Files resources.
+
+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.
+
+The SDK includes `agents.createResponse()` and the saved Assistant conversation
+contract: `instructions`, `contextMode` and text or validated JSON `responseFormat`.
+The typed answer is in `output.text` or `output.json`; retain the returned thread
+for an ordinary `agents.sendMessage()` continuation. Provider refusal, incomplete
+output and invalid JSON do not become a successful parsed answer.
+Native Assistant SSE handles and `watchMessage()` remain local to managed V8
+Components and are excluded from the remote SDK contract.
+
 ## Choose your runtime
 
 | Environment | How to start | Authentication |
@@ -28,14 +81,14 @@ Storage and database contracts; use those declarations when migrating callers.
 | 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`, `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
@@ -52,7 +105,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 2.0.0 does not
+The platform chooses the hosted package version; publishing a new SDK does not
 upgrade existing hosted deployments or their generated package pins.
 
 Hosted user code receives neither a tenant API key nor the private runtime
@@ -71,7 +124,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'],
@@ -102,14 +155,16 @@ JavaScript ignores the additional runtime argument.
 
 Hosted context comes from the current execution snapshot and is synchronous, just
 like the low-code surface. Only platform-backed work returns a promise.
+Account metadata is available through `currentUser.metadata` and
+`currentUser.metadataAdvanced`.
 
 ```js
 export async function init(runtime) {
-  const { api } = runtime;
+  const { api, vault } = runtime;
   const input = api.input();
   const currentUser = api.currentUser();
   const instance = api.getInstanceDetails();
-  const signingSecret = await api.getSecret('WEBHOOK_SIGNING_SECRET');
+  const signingSecret = (await vault.get('WEBHOOK_SIGNING_SECRET', { scope: 'instance' })).revision.value;
 
   api.log({
     message: 'Processing custom component',
@@ -129,6 +184,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:
@@ -196,7 +253,7 @@ There is no `init()` or connection method.
 ## Execute active low-code libraries
 
 `execute(code, options)` runs one transient JavaScript or TypeScript component inside
-RevoEngine. The source has the normal low-code `api` and active tenant `libs.*`
+RevoEngine. The source has the normal low-code `api` and active tenant `lib.*`
 surface. Library functions and source never move into the Node.js process; only the
 JSON-serializable request and execution result cross the runtime transport.
 
@@ -209,8 +266,8 @@ export async function init(runtime) {
   const execution = await runtime.execute(
     `
       const customerId = api.input('customerId');
-      const customer = await libs.Customers.Queries.get(customerId);
-      const balance = await libs.Billing.Balance.current(customerId);
+      const customer = await lib.Customers.Queries.get(customerId);
+      const balance = await lib.Billing.Balance.current(customerId);
       return { customer, balance };
     `,
     {
@@ -245,7 +302,7 @@ type CustomerSummary = {
 const execution = await revo.execute<CustomerSummary>(
   `
     const customerId = api.input('customerId');
-    return libs.Customers.Summary.build(customerId);
+    return lib.Customers.Summary.build(customerId);
   `,
   {
     inputs: { customerId: 'customer-1' },
@@ -259,7 +316,7 @@ console.log(execution.results);
 JavaScript is selected with `language: 'javascript'`; TypeScript is the default.
 The default timeout is 60 seconds. Standalone `executionDefaults` set reusable
 language, timeout, or memory defaults, and per-call options override them.
-One `execute()` call creates one isolated execution. Put related `libs.*`
+One `execute()` call creates one isolated execution. Put related `lib.*`
 operations in the same source when they belong to one workflow. Concurrent separate
 calls still use the SDK's automatic JSON-RPC batching but execute in separate isolates.
 Low-code runtime batches are not retried because source can perform writes.
@@ -317,11 +374,12 @@ Calls queued in the same microtask are grouped. `Promise.all` is the normal way
 to issue a batch:
 
 ```ts
-const [customers, crmToken, activeAgents] = await Promise.all([
+const [customers, crmSecret, activeAgents] = await Promise.all([
   revo.api.getDatabaseData('Customers', { take: 100 }),
-  revo.api.getSecret('CRM_API_TOKEN'),
+  revo.vault.get('CRM_API_TOKEN', { scope: 'instance' }),
   revo.agents.list(),
 ]);
+const crmToken = crmSecret.revision.value;
 ```
 
 Sequential `await` statements naturally produce separate batches:
@@ -387,7 +445,8 @@ export async function init(runtime) {
     args: { userId: currentUser.userId, instanceId, hasInput: input != null },
   });
 
-  return runtime.api.getSecret('SIGNING_SECRET');
+  const signingSecret = await runtime.vault.get('SIGNING_SECRET', { scope: 'instance' });
+  return { configured: Boolean(signingSecret.revision.value) };
 }
 ```
 
@@ -763,3 +822,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.