@revoengine/sdk 3.0.0 → 4.0.0

package/README.md

@@ -8,7 +8,16 @@ Requirements: Node.js 22 or newer.
 
 Development and GitLab CI use Node.js 24.21.0. Run `nvm use` to select the checked-in `.nvmrc`.
 
-## SDK 3.0.0 compatibility
+## 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

package/dist/{errors-D_8Jrrt5.d.cts → errors-CoeJQeU7.d.cts}

@@ -1,9 +1,9 @@
 import * as node_worker_threads from 'node:worker_threads';
 import { Buffer as Buffer$1 } from 'node:buffer';
 
-declare const SDK_VERSION: "3.0.0";
+declare const SDK_VERSION: "4.0.0";
 declare const PROTOCOL_VERSION: 1;
-declare const CONTRACT_REVISION: "a8b45833ea1fa202798a2c8c009e07955b31c0cce159767844f96b9ca85b500a";
+declare const CONTRACT_REVISION: "55a2d6607e14cc2a6f7aef0d21d64a95e6d625d916d6e624bbecb4410716e79a";
 type RuntimeSurfaceName = 'api' | 'storage' | 'transport' | 'vault' | 'serviceAccount' | 'agents' | 'lowCode';
 
 // AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY.
@@ -776,7 +776,7 @@ interface AssistantThreadQuery {
     "cast"?: string;
     /** Optional CTE definitions as a JSON string or bracket-style query object. Only honored by endpoints that explicitly enable dynamic CTEs. */
     "with"?: string;
-    /** Enable debug output for the request, including compiled SQL, bound params, and bounded EXPLAIN plans when the endpoint supports it. */
+    /** Return only the complete estimated read plan without fetching records. count:true adds the count plan. Unsupported data sources reject diagnostic requests without executing the read. */
     "debug"?: boolean;
     /** Include technical response threads alongside conversations. Independent of deleted visibility. */
     "includeResponses"?: boolean;
@@ -1192,7 +1192,7 @@ interface ServiceAccountQuery {
     "cast"?: string;
     /** Optional CTE definitions as a JSON string or bracket-style query object. Only honored by endpoints that explicitly enable dynamic CTEs. */
     "with"?: string;
-    /** Enable debug output for the request, including compiled SQL, bound params, and bounded EXPLAIN plans when the endpoint supports it. */
+    /** Return only the complete estimated read plan without fetching records. count:true adds the count plan. Unsupported data sources reject diagnostic requests without executing the read. */
     "debug"?: boolean;
 }
 interface AssistantActionResolutionInput {
@@ -1689,6 +1689,8 @@ interface SelectJoin {
  * and injects their physical relation and schema metadata automatically.
  */
 interface SelectInput {
+    /** Preview the complete estimated read/count plans without fetching records. */
+    debug?: boolean;
     /**
      * Selected output columns and computed fields.
      * If omitted, the ORM selects all root-table columns by default.
@@ -1746,6 +1748,13 @@ interface DatabaseMutationRequest {
 /**
  * Normal data response returned by the ORM query execution layer.
  */
+/** Full estimated plans only; no data query, COUNT, SQL or bound params in the result. */
+interface DatabaseExplainResult {
+    debug: {
+        explain: string[];
+        countExplain?: string[];
+    };
+}
 interface GetDatabaseDataResponse<T = any> {
     data: T[];
     results: number;
@@ -2399,9 +2408,6 @@ interface Input {
     // Events
     type?: string;
     message?: any;
-    // Execution context.
-    excludeLibs?: string[];
-    includeLibs?: string[];
 }
 type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -2440,12 +2446,14 @@ interface ResourceItem extends BaseProperties {
 interface DatabaseDataActionResponse {
     requested: number;
     success: number;
+    /** Present with conditional upsert options: actual INSERT/UPDATE count. success includes intentionally skipped rows in this mode. */
+    affected?: number;
     elapsed: number;
     /** Omitted when the write is called with `return: false`. */
     data?: any[];
 }
 interface DatabaseDataWriteOptions {
-    /** Defaults to true, preserving the legacy full-row response. */
+    /** Defaults to true. false omits row payloads to reduce response overhead. */
     return?: boolean;
     /** With return enabled, return only primary keys. */
     onlyKeys?: boolean;
@@ -2453,6 +2461,18 @@ interface DatabaseDataWriteOptions {
 interface DatabaseUpsertOptions extends DatabaseDataWriteOptions {
     /** Defaults to true. Set false for the legacy full-replacement conflict behavior. */
     patch?: boolean;
+    /**
+     * Defaults to false. true compares supplied non-primary-key fields.
+     * include or exclude selects the compared fields; the lists are mutually exclusive.
+     * A difference writes every supplied PATCH field. Changes only to excluded fields are skipped.
+     * Omitted fields remain unchanged; JSON uses stored text equality, JSONB uses structural equality.
+     */
+    skipUnchanged?: boolean | {
+        include?: string[];
+        exclude?: string[];
+    };
+    /** Structured predicate on current target values. Controls updates only; missing rows are inserted independently. */
+    filter?: SelectFilterNode;
 }
 interface TruncateDatabaseOptions {
     /**
@@ -2487,7 +2507,7 @@ interface CloneDatabaseCompletedResponse {
     message: string;
 }
 type CloneDatabaseResponse = CloneDatabaseAcceptedResponse | CloneDatabaseCompletedResponse;
-type ExportDatabaseOptions = Omit<SelectInput, 'from'> & {
+type ExportDatabaseOptions = Omit<SelectInput, 'from' | 'debug'> & {
     /**
      * false waits for final storage persistence and returns the completed response.
      * true starts a background export and returns the accepted response.
@@ -2561,13 +2581,13 @@ interface ExportDatabaseCompletedResponse {
     message: string;
 }
 type ExportDatabaseResponse = ExportDatabaseAcceptedResponse | ExportDatabaseCompletedResponse;
-interface DatabaseCountQuery extends Omit<SelectInput, 'take' | 'skip' | 'count' | 'sort'> {
+interface DatabaseCountQuery extends Omit<SelectInput, 'take' | 'skip' | 'count' | 'sort' | 'debug'> {
 }
 /** Omitted take or explicit null selects 2,000 rows; omission warns once per execution. */
 interface DatabaseBoundedReadQuery extends Omit<SelectInput, 'take'> {
     take?: number | null;
 }
-interface DatabaseRowQuery extends Omit<SelectInput, 'take' | 'skip' | 'count'> {
+interface DatabaseRowQuery extends Omit<SelectInput, 'take' | 'skip' | 'count' | 'debug'> {
 }
 interface Context {
     requestId: string;
@@ -3457,7 +3477,13 @@ interface RevoApi {
     deleteDatabase(name: string): Promise<void>;
     restoreDatabase(name: string): Promise<void>;
     truncateDatabase(name: string, options?: TruncateDatabaseOptions): Promise<void>;
-    getDatabaseData<T = any>(name: string, request?: DatabaseBoundedReadQuery): Promise<GetDatabaseDataResponse<T>>;
+    getDatabaseData<T = any>(name: string, request: DatabaseBoundedReadQuery & {
+        debug: true;
+    }): Promise<DatabaseExplainResult>;
+    getDatabaseData<T = any>(name: string, request?: DatabaseBoundedReadQuery & {
+        debug?: false;
+    }): Promise<GetDatabaseDataResponse<T>>;
+    getDatabaseData<T = any>(name: string, request: DatabaseBoundedReadQuery): Promise<GetDatabaseDataResponse<T> | DatabaseExplainResult>;
     getDatabaseDataRow<T = any>(name: string, query: DatabaseRowQuery): Promise<T | null>;
     countDatabase(name: string, query?: DatabaseCountQuery): Promise<number>;
     getDatabaseAudit(name: string, query?: DatabaseAuditQuery): Promise<DatabaseAuditResponse>;

package/dist/{errors-D_8Jrrt5.d.ts → errors-CoeJQeU7.d.ts}

@@ -1,9 +1,9 @@
 import * as node_worker_threads from 'node:worker_threads';
 import { Buffer as Buffer$1 } from 'node:buffer';
 
-declare const SDK_VERSION: "3.0.0";
+declare const SDK_VERSION: "4.0.0";
 declare const PROTOCOL_VERSION: 1;
-declare const CONTRACT_REVISION: "a8b45833ea1fa202798a2c8c009e07955b31c0cce159767844f96b9ca85b500a";
+declare const CONTRACT_REVISION: "55a2d6607e14cc2a6f7aef0d21d64a95e6d625d916d6e624bbecb4410716e79a";
 type RuntimeSurfaceName = 'api' | 'storage' | 'transport' | 'vault' | 'serviceAccount' | 'agents' | 'lowCode';
 
 // AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY.
@@ -776,7 +776,7 @@ interface AssistantThreadQuery {
     "cast"?: string;
     /** Optional CTE definitions as a JSON string or bracket-style query object. Only honored by endpoints that explicitly enable dynamic CTEs. */
     "with"?: string;
-    /** Enable debug output for the request, including compiled SQL, bound params, and bounded EXPLAIN plans when the endpoint supports it. */
+    /** Return only the complete estimated read plan without fetching records. count:true adds the count plan. Unsupported data sources reject diagnostic requests without executing the read. */
     "debug"?: boolean;
     /** Include technical response threads alongside conversations. Independent of deleted visibility. */
     "includeResponses"?: boolean;
@@ -1192,7 +1192,7 @@ interface ServiceAccountQuery {
     "cast"?: string;
     /** Optional CTE definitions as a JSON string or bracket-style query object. Only honored by endpoints that explicitly enable dynamic CTEs. */
     "with"?: string;
-    /** Enable debug output for the request, including compiled SQL, bound params, and bounded EXPLAIN plans when the endpoint supports it. */
+    /** Return only the complete estimated read plan without fetching records. count:true adds the count plan. Unsupported data sources reject diagnostic requests without executing the read. */
     "debug"?: boolean;
 }
 interface AssistantActionResolutionInput {
@@ -1689,6 +1689,8 @@ interface SelectJoin {
  * and injects their physical relation and schema metadata automatically.
  */
 interface SelectInput {
+    /** Preview the complete estimated read/count plans without fetching records. */
+    debug?: boolean;
     /**
      * Selected output columns and computed fields.
      * If omitted, the ORM selects all root-table columns by default.
@@ -1746,6 +1748,13 @@ interface DatabaseMutationRequest {
 /**
  * Normal data response returned by the ORM query execution layer.
  */
+/** Full estimated plans only; no data query, COUNT, SQL or bound params in the result. */
+interface DatabaseExplainResult {
+    debug: {
+        explain: string[];
+        countExplain?: string[];
+    };
+}
 interface GetDatabaseDataResponse<T = any> {
     data: T[];
     results: number;
@@ -2399,9 +2408,6 @@ interface Input {
     // Events
     type?: string;
     message?: any;
-    // Execution context.
-    excludeLibs?: string[];
-    includeLibs?: string[];
 }
 type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -2440,12 +2446,14 @@ interface ResourceItem extends BaseProperties {
 interface DatabaseDataActionResponse {
     requested: number;
     success: number;
+    /** Present with conditional upsert options: actual INSERT/UPDATE count. success includes intentionally skipped rows in this mode. */
+    affected?: number;
     elapsed: number;
     /** Omitted when the write is called with `return: false`. */
     data?: any[];
 }
 interface DatabaseDataWriteOptions {
-    /** Defaults to true, preserving the legacy full-row response. */
+    /** Defaults to true. false omits row payloads to reduce response overhead. */
     return?: boolean;
     /** With return enabled, return only primary keys. */
     onlyKeys?: boolean;
@@ -2453,6 +2461,18 @@ interface DatabaseDataWriteOptions {
 interface DatabaseUpsertOptions extends DatabaseDataWriteOptions {
     /** Defaults to true. Set false for the legacy full-replacement conflict behavior. */
     patch?: boolean;
+    /**
+     * Defaults to false. true compares supplied non-primary-key fields.
+     * include or exclude selects the compared fields; the lists are mutually exclusive.
+     * A difference writes every supplied PATCH field. Changes only to excluded fields are skipped.
+     * Omitted fields remain unchanged; JSON uses stored text equality, JSONB uses structural equality.
+     */
+    skipUnchanged?: boolean | {
+        include?: string[];
+        exclude?: string[];
+    };
+    /** Structured predicate on current target values. Controls updates only; missing rows are inserted independently. */
+    filter?: SelectFilterNode;
 }
 interface TruncateDatabaseOptions {
     /**
@@ -2487,7 +2507,7 @@ interface CloneDatabaseCompletedResponse {
     message: string;
 }
 type CloneDatabaseResponse = CloneDatabaseAcceptedResponse | CloneDatabaseCompletedResponse;
-type ExportDatabaseOptions = Omit<SelectInput, 'from'> & {
+type ExportDatabaseOptions = Omit<SelectInput, 'from' | 'debug'> & {
     /**
      * false waits for final storage persistence and returns the completed response.
      * true starts a background export and returns the accepted response.
@@ -2561,13 +2581,13 @@ interface ExportDatabaseCompletedResponse {
     message: string;
 }
 type ExportDatabaseResponse = ExportDatabaseAcceptedResponse | ExportDatabaseCompletedResponse;
-interface DatabaseCountQuery extends Omit<SelectInput, 'take' | 'skip' | 'count' | 'sort'> {
+interface DatabaseCountQuery extends Omit<SelectInput, 'take' | 'skip' | 'count' | 'sort' | 'debug'> {
 }
 /** Omitted take or explicit null selects 2,000 rows; omission warns once per execution. */
 interface DatabaseBoundedReadQuery extends Omit<SelectInput, 'take'> {
     take?: number | null;
 }
-interface DatabaseRowQuery extends Omit<SelectInput, 'take' | 'skip' | 'count'> {
+interface DatabaseRowQuery extends Omit<SelectInput, 'take' | 'skip' | 'count' | 'debug'> {
 }
 interface Context {
     requestId: string;
@@ -3457,7 +3477,13 @@ interface RevoApi {
     deleteDatabase(name: string): Promise<void>;
     restoreDatabase(name: string): Promise<void>;
     truncateDatabase(name: string, options?: TruncateDatabaseOptions): Promise<void>;
-    getDatabaseData<T = any>(name: string, request?: DatabaseBoundedReadQuery): Promise<GetDatabaseDataResponse<T>>;
+    getDatabaseData<T = any>(name: string, request: DatabaseBoundedReadQuery & {
+        debug: true;
+    }): Promise<DatabaseExplainResult>;
+    getDatabaseData<T = any>(name: string, request?: DatabaseBoundedReadQuery & {
+        debug?: false;
+    }): Promise<GetDatabaseDataResponse<T>>;
+    getDatabaseData<T = any>(name: string, request: DatabaseBoundedReadQuery): Promise<GetDatabaseDataResponse<T> | DatabaseExplainResult>;
     getDatabaseDataRow<T = any>(name: string, query: DatabaseRowQuery): Promise<T | null>;
     countDatabase(name: string, query?: DatabaseCountQuery): Promise<number>;
     getDatabaseAudit(name: string, query?: DatabaseAuditQuery): Promise<DatabaseAuditResponse>;