@revoengine/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RevoEngine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,639 @@
+# @revoengine/sdk
+
+Official Node.js SDK for RevoEngine. It provides the modern `api`, `utils`,
+`storage`, and `agents` namespaces plus the `batch` controller in both
+Revo-hosted `CUSTOM_NODEJS` components and standalone Node.js applications.
+
+Requirements: Node.js 22 or newer.
+
+## Choose your runtime
+
+| Environment | How to start | Authentication |
+| --- | --- | --- |
+| 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`
+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 |
+| Local `utils` and `batch.configure()` | Synchronous unless the utility is inherently asynchronous | Same |
+
+## Installation
+
+Standalone applications install the SDK normally:
+
+```sh
+npm install @revoengine/sdk
+```
+
+New Revo-hosted components receive `@revoengine/sdk: "1.0.0"` 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"
+  }
+}
+```
+
+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
+worker owns the short-lived, execution-bound bridge. The
+`@revoengine/sdk/hosted` entrypoint is platform-internal and must not be
+imported by a component.
+
+## Revo-hosted CUSTOM_NODEJS
+
+### Basic entrypoint
+
+Export a named `init` function. Do not construct `RevoClient` and do not call a
+separate initialization method.
+
+```js
+/** @param {import('@revoengine/sdk').RevoRuntime} runtime */
+export async function init(runtime) {
+  const { api, utils, storage, agents, batch } = runtime;
+  const { data: rows, next } = await api.getDatabaseData('Sales', {
+    fields: ['saleId', 'customerId', 'total', 'createdAt'],
+    sort: ['-createdAt'],
+    take: 25,
+  });
+
+  const file = await storage.putObject({
+    name: `sales-${utils.randomUUID()}.json`,
+    data: JSON.stringify({ rows, next }),
+    mimeType: 'application/json',
+  });
+
+  return {
+    storageEntryId: file.storageEntryId,
+    exportedRows: rows.length,
+    hasNextPage: next,
+  };
+}
+```
+
+`putObject()` is appropriate here because this is a deliberately small JSON
+payload. Use an upload session for larger exports, as shown below.
+
+Existing components that export `async function init()` remain compatible;
+JavaScript ignores the additional runtime argument.
+
+### Input, context, and secrets
+
+Hosted context comes from the current execution snapshot and is synchronous, just
+like the low-code surface. Only platform-backed work returns a promise.
+
+```js
+export async function init(runtime) {
+  const { api } = runtime;
+  const input = api.input();
+  const currentUser = api.currentUser();
+  const instance = api.getInstanceDetails();
+  const signingSecret = await api.getSecret('WEBHOOK_SIGNING_SECRET');
+
+  api.log({
+    message: 'Processing custom component',
+    args: {
+      userId: currentUser.userId,
+      instanceId: instance.id,
+      hasInput: input != null,
+    },
+  });
+
+  // Use the secret without returning or logging its value.
+  return { accepted: Boolean(signingSecret) };
+}
+```
+
+Execution-only methods such as `api.input()`, `api.getContext()`,
+`api.getExecutionId()`, and `api.getOperationId()` are available only in hosted
+executions.
+
+### Configure hosted batching
+
+Configure batching before the first remote call:
+
+```js
+export async function init(runtime) {
+  runtime.batch.configure({
+    failureMode: 'stop',
+    maxCalls: 16,
+    maxInFlight: 2,
+  });
+
+  const [customers, agents] = await Promise.all([
+    runtime.api.getDatabaseData('Customers', { take: 100 }),
+    runtime.agents.list(),
+  ]);
+
+  return {
+    customers: customers.data,
+    agents,
+  };
+}
+```
+
+`batch.configure()` is synchronous and rejects changes after the first remote
+batch has been dispatched.
+
+## Standalone Node.js
+
+### Basic client
+
+Constructing `RevoClient` is synchronous and performs no network I/O. The first
+platform-backed call validates the API key through `/api/v1/me`, reads the
+instance bound to that key, discovers its Sandbox endpoint, and dispatches the
+queued runtime batch.
+
+```ts
+import { RevoClient } from '@revoengine/sdk';
+
+const apiKey = process.env.REVO_API_KEY;
+if (!apiKey) throw new Error('REVO_API_KEY is required.');
+
+const revo = new RevoClient({
+  apiKey,
+});
+
+type Sale = {
+  saleId: string;
+  customerId: string;
+  total: number;
+  createdAt: string;
+};
+
+const result = await revo.api.getDatabaseData<Sale>('Sales', {
+  filter: { field: 'total', op: 'gte', value: 100 },
+  sort: ['-createdAt'],
+  take: 100,
+});
+
+console.log(result.data);
+```
+
+There is no `init()` or connection method.
+
+### Environment configuration
+
+```ts
+const revo = new RevoClient();
+```
+
+Supported environment aliases, in precedence order after explicit constructor
+options:
+
+- URL: `REVO_URL`, `REVO_BASE_URL`, `REVOENGINE_URL`, `REVOENGINE_BASE_URL`
+- API key: `REVO_TOKEN`, `REVO_API_KEY`, `REVOENGINE_TOKEN`, `REVOENGINE_API_KEY`
+
+The default API URL is `https://api.revoengine.com`. The API key already
+identifies its instance, so `RevoClient` has no instance option and sends no
+separate instance header. `/api/v1/me` is the sole source of the bound instance
+identity and Sandbox endpoint.
+
+Keep the API key in a server-side secret or environment variable. This SDK is
+for Node.js processes and must not be bundled into browser code with a key.
+
+Explicit options always win:
+
+```ts
+const apiKey = process.env.REVO_API_KEY;
+if (!apiKey) throw new Error('REVO_API_KEY is required.');
+
+const revo = new RevoClient({
+  baseUrl: 'https://api.revoengine.com',
+  apiKey,
+  requestTimeoutMs: 30_000,
+  batch: {
+    failureMode: 'independent',
+    maxCalls: 16,
+    maxRequestBytes: 128 * 1024,
+    maxInFlight: 2,
+    maxQueuedCalls: 256,
+  },
+});
+```
+
+The SDK never reads or writes Revo CLI credential files.
+
+## Automatic batching
+
+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([
+  revo.api.getDatabaseData('Customers', { take: 100 }),
+  revo.api.getSecret('CRM_API_TOKEN'),
+  revo.agents.list(),
+]);
+```
+
+Sequential `await` statements naturally produce separate batches:
+
+```ts
+const customers = await revo.api.getDatabaseData('Customers', { take: 100 });
+const agents = await revo.agents.list();
+```
+
+The default `independent` mode executes every valid call and settles each
+promise independently. In `stop` mode calls execute in order; after one call
+fails, later calls in that batch reject with `BATCH_STOPPED`.
+
+```ts
+const revo = new RevoClient({
+  batch: { failureMode: 'stop' },
+});
+```
+
+Defaults are 32 calls per request, 256 KiB per request, four in-flight batches,
+and 1,024 queued calls. Client configuration can only lower server ceilings.
+The complete batch is validated before any call executes.
+
+Runtime batches are never retried automatically because they may contain
+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.
+
+## Local utils
+
+`utils` runs locally and is available before authentication or discovery:
+
+```ts
+const payload = JSON.stringify({ event: 'customer.updated' });
+const secret = process.env.SIGNING_SECRET;
+if (!secret) throw new Error('SIGNING_SECRET is required.');
+
+const requestId = revo.utils.randomUUID();
+const signature = revo.utils.hmac(payload, secret);
+const encoded = revo.utils.encodeBase64('RevoEngine');
+```
+
+Only the modern first-class utility surface is exposed; deprecated low-code
+aliases are not included. `utils.sleep()`, `utils.generateHash()`, and
+`utils.compareHash()` remain asynchronous by design; the other local utilities
+return their values directly.
+
+## Runtime context
+
+Hosted context reads are synchronous because the generated worker injects an
+immutable execution snapshot before `init(runtime)`:
+
+```js
+export async function init(runtime) {
+  const input = runtime.api.input();
+  const currentUser = runtime.api.currentUser();
+  const instanceId = runtime.api.getCurrentInstance();
+
+  runtime.api.log({
+    message: 'Started',
+    args: { userId: currentUser.userId, instanceId, hasInput: input != null },
+  });
+
+  return runtime.api.getSecret('SIGNING_SECRET');
+}
+```
+
+The three standalone identity methods are asynchronous because their first call
+performs lazy `/api/v1/me` discovery and later calls use the cached profile:
+
+```ts
+const [currentUser, instanceId, instance] = await Promise.all([
+  revo.api.currentUser(),
+  revo.api.getCurrentInstance(),
+  revo.api.getInstanceDetails(),
+]);
+```
+
+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.
+
+## Storage
+
+### Small text or binary objects
+
+`storage.putObject()` is convenient for small payloads that fit the runtime
+batch limit:
+
+```ts
+const settingsFile = await revo.storage.putObject({
+  name: 'settings.json',
+  data: JSON.stringify({ locale: 'pl-PL', enabled: true }),
+  dataEncoding: 'utf8',
+  mimeType: 'application/json',
+});
+
+async function uploadSmallPdf(pdfBuffer: Buffer) {
+  return revo.storage.putObject({
+    name: 'invoice.pdf',
+    data: pdfBuffer.toString('base64'),
+    dataEncoding: 'base64',
+    mimeType: 'application/pdf',
+  });
+}
+```
+
+### Large binary uploads
+
+Large files must use an upload session or signed URL so their bytes do not enter
+the JSON runtime batch:
+
+```ts
+import type { RevoRuntime } from '@revoengine/sdk';
+
+export async function uploadBinary(
+  runtime: Pick<RevoRuntime, 'storage'>,
+  name: string,
+  contentType: string,
+  bytes: Uint8Array,
+) {
+  const { session, upload } = await runtime.storage.createUploadSession({
+    name,
+    contentTypeHint: contentType,
+    sizeHint: bytes.byteLength,
+    uploadMode: 'direct',
+  });
+
+  const sessionId = session.storageUploadSessionId;
+
+  try {
+    if (!upload.uploadUrl) {
+      throw new Error('RevoEngine did not return a direct upload URL.');
+    }
+
+    const headers = new Headers(upload.headers);
+    if (!headers.has('content-type')) {
+      headers.set('content-type', contentType);
+    }
+
+    const response = await fetch(upload.uploadUrl, {
+      method: upload.method,
+      headers,
+      body: Buffer.from(bytes),
+    });
+    if (!response.ok) {
+      throw new Error(`Upload failed with HTTP ${response.status}.`);
+    }
+
+    const { entry } = await runtime.storage.finalizeUploadSession(sessionId);
+    return entry;
+  } catch (error) {
+    await runtime.storage.abortUploadSession(sessionId).catch(() => undefined);
+    throw error;
+  }
+}
+```
+
+The helper accepts either a `RevoClient` or the runtime injected into hosted
+`init(runtime)`. Session creation, finalization, and best-effort abort remain
+runtime calls; only the binary bytes bypass the JSON batch.
+
+## Excel export from database data
+
+Install `exceljs` in your standalone application or add it to the hosted
+component's `package.json` dependencies.
+
+```ts
+import ExcelJS from 'exceljs';
+import type { RevoRuntime } from '@revoengine/sdk';
+import { uploadBinary } from './upload-binary.js';
+
+type SaleRow = {
+  saleId: string;
+  customerId: string;
+  total: number;
+  createdAt: string;
+};
+
+type ExportRuntime = Pick<RevoRuntime, 'storage'> & {
+  readonly api: Pick<RevoRuntime['api'], 'getDatabaseData'>;
+};
+
+export async function exportSales(
+  runtime: ExportRuntime,
+) {
+  const workbook = new ExcelJS.Workbook();
+  const sheet = workbook.addWorksheet('Sales');
+  sheet.columns = [
+    { header: 'Sale ID', key: 'saleId' },
+    { header: 'Customer', key: 'customerId' },
+    { header: 'Total', key: 'total' },
+    { header: 'Created at', key: 'createdAt' },
+  ];
+
+  let skip = 0;
+  for (;;) {
+    const page = await runtime.api.getDatabaseData<SaleRow>('Sales', {
+      fields: ['saleId', 'customerId', 'total', 'createdAt'],
+      sort: { saleId: 'ASC' },
+      take: 1_000,
+      skip,
+    });
+
+    sheet.addRows(page.data);
+    if (!page.next) break;
+    if (page.results === 0) {
+      throw new Error('Sales pagination did not advance.');
+    }
+    skip += page.results;
+  }
+
+  const bytes = Buffer.from(await workbook.xlsx.writeBuffer());
+  return uploadBinary(
+    runtime,
+    'sales-export.xlsx',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    bytes,
+  );
+}
+```
+
+Standalone call site:
+
+```ts
+import { RevoClient } from '@revoengine/sdk';
+import { exportSales } from './export-sales.js';
+
+const revo = new RevoClient();
+const file = await exportSales(revo);
+console.log(file.storageEntryId);
+```
+
+The same exporter can be used in Revo-hosted code:
+
+```js
+import { exportSales } from './export-sales.js';
+
+export async function init(runtime) {
+  const file = await exportSales(runtime);
+  return { storageEntryId: file.storageEntryId };
+}
+```
+
+The stable unique sort makes offset pagination deterministic. If the table can
+change during export, filter on an immutable snapshot/version marker so later
+pages describe the same logical dataset.
+
+## PDF generation
+
+Install `pdfkit` in your application or hosted component dependencies:
+
+```ts
+import PDFDocument from 'pdfkit';
+import type { RevoRuntime } from '@revoengine/sdk';
+import { uploadBinary } from './upload-binary.js';
+
+function renderCustomerPdf(customer: unknown): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const document = new PDFDocument({ margin: 48 });
+    const chunks: Buffer[] = [];
+
+    document.on('data', (chunk: Buffer) => chunks.push(chunk));
+    document.on('error', reject);
+    document.on('end', () => resolve(Buffer.concat(chunks)));
+
+    document.fontSize(18).text('Customer summary');
+    document.moveDown();
+    document.fontSize(10).text(JSON.stringify(customer, null, 2));
+    document.end();
+  });
+}
+
+type ExportRuntime = Pick<RevoRuntime, 'storage'> & {
+  readonly api: Pick<RevoRuntime['api'], 'getDatabaseData'>;
+};
+
+export async function exportCustomer(
+  runtime: ExportRuntime,
+  customerId: string,
+) {
+  const { data } = await runtime.api.getDatabaseData('Customers', {
+    filter: { field: 'customerId', op: 'eq', value: customerId },
+    take: 1,
+  });
+  if (!data[0]) throw new Error(`Customer ${customerId} was not found.`);
+
+  const pdf = await renderCustomerPdf(data[0]);
+  return uploadBinary(runtime, `customer-${customerId}.pdf`, 'application/pdf', pdf);
+}
+```
+
+Standalone call site:
+
+```ts
+import { RevoClient } from '@revoengine/sdk';
+import { exportCustomer } from './export-customer.js';
+
+const revo = new RevoClient();
+const file = await exportCustomer(revo, 'customer-1');
+console.log(file.storageEntryId);
+```
+
+Revo-hosted call site:
+
+```js
+import { exportCustomer } from './export-customer.js';
+
+export async function init(runtime) {
+  const input = runtime.api.input();
+  if (!input || typeof input.customerId !== 'string') {
+    throw new Error('customerId input is required.');
+  }
+  const file = await exportCustomer(runtime, input.customerId);
+  return { storageEntryId: file.storageEntryId };
+}
+```
+
+## Jobs and agents
+
+```ts
+const jobId = await revo.api.triggerJob(
+  '8f1fe47f-90e6-4c16-a9ea-ccba5ca2a8da',
+  { customerId: 'customer-1' },
+);
+
+const agents = await revo.agents.list();
+const agentId = agents[0]?.agentId;
+if (agentId) {
+  const run = await revo.agents.startRun(agentId, {
+    instruction: `Process the result of job ${jobId}.`,
+    triggerType: 'REQUEST',
+    triggerRefType: 'JOB',
+    triggerRefId: jobId,
+    state: { jobId },
+  });
+  console.log(run.agentRunId);
+}
+```
+
+Available methods and request types are exported through the package's
+TypeScript declarations. The generated declarations are the canonical SDK
+contract for the installed version.
+
+## Error handling
+
+All SDK errors derive from `RevoError`:
+
+```ts
+import {
+  RevoError,
+  RevoRemoteError,
+  RevoTransportError,
+} from '@revoengine/sdk';
+
+try {
+  await revo.api.insertDatabaseData('Sales', [{ saleId: 'sale-1' }]);
+} catch (error) {
+  if (error instanceof RevoTransportError && error.indeterminate) {
+    // The request may have reached RevoEngine. Check by idempotency key or
+    // business identifier before attempting the mutation again.
+    throw error;
+  }
+  if (error instanceof RevoRemoteError) {
+    console.error(error.code, error.statusCode, error.message);
+    throw error;
+  }
+  if (error instanceof RevoError) {
+    console.error(error.code, error.message);
+    throw error;
+  }
+  throw error;
+}
+```
+
+Common subclasses include:
+
+- `RevoConfigurationError`
+- `RevoAuthenticationError`
+- `RevoPermissionDeniedError`
+- `RevoRuntimeContextUnavailableError`
+- `RevoBatchConfigurationError`
+- `RevoBatchLimitError`
+- `RevoRemoteError`
+- `RevoProtocolError`
+- `RevoTransportError`
+
+## SDK 1.0 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.
+- Deprecated low-code methods and aliases are excluded.
+- `api.transactionDatabaseData` is excluded from 1.0.0.
+- Runtime batches are non-transactional and are not retried automatically.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,30 @@
+# Third-party notices
+
+The published `@revoengine/sdk` JavaScript bundles incorporate the following
+third-party packages. This inventory is generated from the shipped bundle source
+maps and is checked against the repository license policy on every release.
+
+| Package | Version | License |
+| --- | ---: | --- |
+| `buffer-equal-constant-time` | `1.0.1` | `BSD-3-Clause` |
+| `copy-anything` | `4.1.0` | `MIT` |
+| `ecdsa-sig-formatter` | `1.0.11` | `Apache-2.0` |
+| `jsonwebtoken` | `9.0.3` | `MIT` |
+| `jwa` | `2.0.1` | `MIT` |
+| `jws` | `4.0.1` | `MIT` |
+| `lodash.includes` | `4.3.0` | `MIT` |
+| `lodash.isboolean` | `3.0.3` | `MIT` |
+| `lodash.isinteger` | `4.0.4` | `MIT` |
+| `lodash.isnumber` | `3.0.3` | `MIT` |
+| `lodash.isplainobject` | `4.0.6` | `MIT` |
+| `lodash.isstring` | `4.0.1` | `MIT` |
+| `lodash.once` | `4.1.1` | `MIT` |
+| `ms` | `2.1.3` | `MIT` |
+| `object-hash` | `3.0.0` | `MIT` |
+| `safe-buffer` | `5.2.1` | `MIT` |
+| `semver` | `7.8.5` | `ISC` |
+| `superjson` | `2.2.6` | `MIT` |
+| `uuid` | `13.0.2` | `MIT` |
+
+The complete license texts are distributed in
+[`licenses/THIRD_PARTY_LICENSES.txt`](licenses/THIRD_PARTY_LICENSES.txt).