@revoengine/sdk 1.0.0 → 1.5.5

package/README.md

@@ -1,11 +1,26 @@
 # @revoengine/sdk
 
 Official Node.js SDK for RevoEngine. It provides the modern `api`, `utils`,
-`storage`, and `agents` namespaces plus the `batch` controller in both
+`storage`, 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
+
+This major 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.
+
+HTTP Storage requests/responses now use `requestType: 'storage'` and
+`responseType: 'storage'`, with flat Storage-only `source` / `target` objects.
+Legacy HTTP Files references and the old Storage `stream` mode are rejected.
+Byte/SSE response iterators remain local to V8 and are blocked by the SDK before
+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.
+
 ## Choose your runtime
 
 | Environment | How to start | Authentication |
@@ -13,14 +28,14 @@ Requirements: Node.js 22 or newer.
 | 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`, and `batch`
+Both modes expose the same `api`, `utils`, `storage`, `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`, and `agents` calls | Asynchronous | Asynchronous |
+| Remote `api`, `storage`, `agents`, and `execute()` calls | Asynchronous | Asynchronous |
 | Local `utils` and `batch.configure()` | Synchronous unless the utility is inherently asynchronous | Same |
 
 ## Installation
@@ -31,22 +46,14 @@ Standalone applications install the SDK normally:
 npm install @revoengine/sdk
 ```
 
-New Revo-hosted components receive `@revoengine/sdk: "1.0.0"` and a JSDoc
+New Revo-hosted components receive the exact platform-supported SDK version and a JSDoc
 `RevoRuntime` type import in their generated starter files.
 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 relevant generated `package.json` fields are:
-
-```json
-{
-  "type": "module",
-  "dependencies": {
-    "@revoengine/sdk": "1.0.0"
-  }
-}
-```
+The platform chooses the hosted package version; publishing SDK 2.0.0 does not
+upgrade existing hosted deployments or their generated package pins.
 
 Hosted user code receives neither a tenant API key nor the private runtime
 credential and does not perform `/api/v1/me` discovery. The generated parent
@@ -64,7 +71,7 @@ separate initialization method.
 ```js
 /** @param {import('@revoengine/sdk').RevoRuntime} runtime */
 export async function init(runtime) {
-  const { api, utils, storage, agents, batch } = runtime;
+  const { api, utils, storage, agents, execute, batch } = runtime;
   const { data: rows, next } = await api.getDatabaseData('Sales', {
     fields: ['saleId', 'customerId', 'total', 'createdAt'],
     sort: ['-createdAt'],
@@ -186,6 +193,77 @@ console.log(result.data);
 
 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.*`
+surface. Library functions and source never move into the Node.js process; only the
+JSON-serializable request and execution result cross the runtime transport.
+
+Revo-hosted `CUSTOM_NODEJS`:
+
+```js
+/** @param {import('@revoengine/sdk').RevoRuntime} runtime */
+export async function init(runtime) {
+  const customerId = runtime.api.input('customerId');
+  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);
+      return { customer, balance };
+    `,
+    {
+      inputs: { customerId },
+      timeoutMs: 10_000,
+    },
+  );
+
+  return execution.results;
+}
+```
+
+Standalone Node.js:
+
+```ts
+import { RevoClient } from '@revoengine/sdk';
+
+const revo = new RevoClient({
+  apiKey: process.env.REVO_API_KEY,
+  executionDefaults: {
+    timeoutMs: 60_000,
+    memory: 256,
+  },
+});
+
+type CustomerSummary = {
+  customerId: string;
+  name: string;
+  balance: number;
+};
+
+const execution = await revo.execute<CustomerSummary>(
+  `
+    const customerId = api.input('customerId');
+    return libs.Customers.Summary.build(customerId);
+  `,
+  {
+    inputs: { customerId: 'customer-1' },
+    timeoutMs: 10_000,
+  },
+);
+
+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.*`
+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.
+
 ### Environment configuration
 
 ```ts
@@ -216,6 +294,11 @@ const revo = new RevoClient({
   baseUrl: 'https://api.revoengine.com',
   apiKey,
   requestTimeoutMs: 30_000,
+  executionDefaults: {
+    language: 'typescript',
+    timeoutMs: 60_000,
+    memory: 256,
+  },
   batch: {
     failureMode: 'independent',
     maxCalls: 16,
@@ -267,7 +350,7 @@ mutations. If transport is interrupted after dispatch, unresolved calls reject
 with `RevoTransportError` and `indeterminate: true`.
 
 Batching is not a transaction. `api.transactionDatabaseData` is intentionally
-not part of SDK 1.0.0.
+not part of the SDK.
 
 ## Local utils
 
@@ -323,6 +406,49 @@ Other context methods throw `RevoRuntimeContextUnavailableError` synchronously
 outside a hosted execution. The distinct `RevoApi` and `RevoStandaloneApi` types
 make the hosted snapshot and standalone discovery behavior explicit.
 
+## HTTP calls
+
+`api.httpCall(request, options)` supports ordinary JSON/text/base64/document responses
+and HTTP-to-Storage transfers through both the standalone and hosted SDK:
+
+```ts
+const response = await revo.api.httpCall(
+  { url: 'https://example.com/report.pdf', method: 'GET' },
+  { responseType: 'storage', target: { name: 'report.pdf' } },
+);
+if (response.status >= 200 && response.status < 300 && response.storage) {
+  console.log(response.storage.entry);
+}
+```
+
+Use `requestType: 'storage'` with `source: { storageEntryId }` for a Storage request
+body. Request and response modes are independent. Source/target references are flat
+Storage objects; Files, nested `storage` and raw string identifiers are rejected.
+Targets can create an entry, replace it using `{ storageEntryId, replace: true }`,
+or fill and finalize an existing empty direct session using `{ storageUploadSessionId }`.
+Only 2xx responses write Storage; other statuses return bounded diagnostic data.
+
+`responseType: 'stream'` (bytes/SSE) is deliberately absent from SDK declarations
+and rejects before discovery, queueing or transport, including the hosted
+`CUSTOM_NODEJS` bridge. Storage responses remain supported. Local low-code V8 and
+agent `code_exec` do support stream iterators: consume them inside the low-code
+body, then return bounded serializable data. An SDK `execute(...)` call may run
+such a body; it cannot return its iterator through the JSON transport.
+
+### Developing coordinated platform contracts
+
+After regenerating platform declarations, synchronize this checkout with:
+
+```sh
+REVOENGINE_PLATFORM_PATH=/path/to/platform node scripts/sync-contract.mjs --working-tree
+REVOENGINE_PLATFORM_PATH=/path/to/platform npm run contract:check -- --working-tree
+```
+
+Working-tree snapshots are explicitly unreleasable: the normal provenance/CI check
+continues to require committed platform sources. After committing the platform
+changes, run `sync-contract.mjs` without `--working-tree`, then run the normal
+`contract:check` against that pinned commit before releasing the SDK.
+
 ## Storage
 
 ### Small text or binary objects
@@ -628,12 +754,12 @@ Common subclasses include:
 - `RevoProtocolError`
 - `RevoTransportError`
 
-## SDK 1.0 compatibility notes
+## SDK compatibility notes
 
 - Node.js 22 or newer is required.
 - The package provides ESM, CommonJS, and TypeScript declarations.
 - The package has no runtime dependencies.
-- No package-level `api`, `utils`, `storage`, or `agents` singleton is exported.
+- No package-level `api`, `utils`, `storage`, `agents`, or `execute` singleton is exported.
 - Deprecated low-code methods and aliases are excluded.
-- `api.transactionDatabaseData` is excluded from 1.0.0.
+- `api.transactionDatabaseData` is excluded.
 - Runtime batches are non-transactional and are not retried automatically.