@revoengine/sdk 1.0.1 → 1.5.6

package/README.md

@@ -1,11 +1,33 @@
 # @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`, 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.6 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.
+
+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.
+
+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)
+for Secret formats and file-transfer examples.
+
 ## Choose your runtime
 
 | Environment | How to start | Authentication |
@@ -13,7 +35,7 @@ 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`, `execute`, and `batch`
+Both modes expose the same `api`, `utils`, `storage`, `transport`, `agents`, `execute`, and `batch`
 properties, but return types reflect where the work happens:
 
 | Call kind | Revo-hosted | Standalone |
@@ -37,16 +59,8 @@ 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.1"
-  }
-}
-```
+The platform chooses the hosted package version; publishing SDK 1.5.6 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
@@ -399,6 +413,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