@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/dist/utility/errors/hdbError.js

@@ -1,12 +1,58 @@
 'use strict';
-const hdbErrors = require('./commonErrors.js');
-const hdbTerms = require("../hdbTerms.js");
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hdbErrors = exports.AccessViolation = exports.Violation = exports.ServerError = exports.ClientError = exports.HdbError = void 0;
+exports.handleHDBError = handleHDBError;
+exports.isHDBError = isHDBError;
+const harper_logger_ts_1 = __importDefault(require("../logging/harper_logger.js"));
+const hdbErrors = __importStar(require("./commonErrors.js"));
+exports.hdbErrors = hdbErrors;
+const hdbTerms = __importStar(require("../hdbTerms.js"));
 /**
  * Custom error class used for better error and log handling.  Caught errors that evaluate to an instanceof HdbError can
  * be handled differently - e.g. in most cases caught HdbError likely would not need to be logged since that should have
  * already been handled when the custom error was constructed.
  */
 class HdbError extends Error {
+    statusCode;
+    http_resp_msg;
+    type;
+    logLevel;
     /**
      * @param {Error} errOrig -  Error to be translated into HdbError. If manually throwing an error, pass `new Error()` to ensure stack trace is maintained
      * @param {String} [httpMsg] - optional -  response message that will be returned via the API
@@ -33,12 +79,13 @@ class HdbError extends Error {
             this.stack = errOrig.stack;
         }
         if (logMsg) {
-            const logger = require('../logging/harper_logger.js');
-            logger[logLevel](logMsg);
+            harper_logger_ts_1.default[logLevel](logMsg);
         }
     }
 }
+exports.HdbError = HdbError;
 class ClientError extends Error {
+    statusCode;
     constructor(message, statusCode) {
         if (message instanceof Error) {
             message.statusCode = statusCode || 400;
@@ -48,12 +95,15 @@ class ClientError extends Error {
         this.statusCode = statusCode || 400;
     }
 }
+exports.ClientError = ClientError;
 class ServerError extends Error {
+    statusCode;
     constructor(message, statusCode) {
         super(message);
         this.statusCode = statusCode || 500;
     }
 }
+exports.ServerError = ServerError;
 /**
  * This handler method is used to effectively evaluate caught errors and either translates them into a custom HdbError or,
  * if it is already a HdbError, just returns the error to continue being thrown up the stack
@@ -79,27 +129,25 @@ function handleHDBError(e, httpMsg, httpCode, logLevel = hdbTerms.LOG_LEVELS.ERR
     return error;
 }
 /**
- * Represents a general violation of validation/authorization. This should be used in situations where we are performing
- * expected verification, and we do not need to record a stack trace. This extends Error's prototype, but doesn't
- * use the native constructor to avoid stack trace capture which is several times faster.
+ * Represents a general violation of validation/authorization. This is used in situations where we are performing
+ * expected verification. Extends Error for TypeScript class compatibility.
  * @param {Object} user - user object that caused the access violation
  * @constructor
  */
-function Violation(message) {
-    this.message = message;
+class Violation extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
 }
-Violation.prototype = Object.create(Error.prototype);
-Violation.prototype.constructor = Violation;
-Violation.prototype.toString = function () {
-    return `${this.constructor.name}: ${this.message}`;
-};
+exports.Violation = Violation;
 /**
- * Represents an access violation. This is used to return a 403 or 401 response to the client. Uses fast Violation class
- * to avoid stack trace capture.
+ * Represents an access violation. This is used to return a 403 or 401 response to the client.
  * @param {Object} user - user object that caused the access violation
  * @constructor
  */
 class AccessViolation extends Violation {
+    statusCode;
     constructor(user) {
         if (user) {
             super('Unauthorized access to resource');
@@ -112,17 +160,8 @@ class AccessViolation extends Violation {
         }
     }
 }
+exports.AccessViolation = AccessViolation;
 function isHDBError(e) {
     return e.__proto__.constructor.name === HdbError.name;
 }
-module.exports = {
-    isHDBError,
-    handleHDBError,
-    ClientError,
-    ServerError,
-    AccessViolation,
-    Violation,
-    //Including common hdbErrors here so that they can be brought into modules on the same line where the handler method is brought in
-    hdbErrors,
-};
 //# sourceMappingURL=hdbError.js.map

package/dist/utility/errors/hdbError.js.map

@@ -1 +1 @@
-{"version":3,"file":"hdbError.js","sourceRoot":"","sources":["../../../utility/errors/hdbError.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"hdbError.js","sourceRoot":"","sources":["../../../utility/errors/hdbError.ts"],"names":[],"mappings":"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"}

package/dist/utility/expandEnvVar.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Environment-variable expansion for config-loaded values.
+ *
+ * Harper's config parser does not expand `${VAR}` placeholders itself — the
+ * `harperdb-config.yaml` value lands in memory verbatim. Component code that
+ * needs to support env-var indirection (secrets, host overrides, etc.)
+ * applies these helpers to its own config entries.
+ *
+ * The pattern matches the convention established by the OAuth component
+ * (`@harperfast/oauth`'s `src/lib/config.ts`); kept identical so operator
+ * documentation and config snippets carry over verbatim.
+ *
+ * Matching rules:
+ * - Only **whole-string** `${VAR_NAME}` placeholders match. Partial expansion
+ *   (e.g. `'http://${HOST}:9926'`) is NOT supported by design — keeps the
+ *   substitution boundary unambiguous and avoids accidental injection into
+ *   structured values.
+ * - When the env var is undefined, the **original placeholder string is
+ *   returned unchanged**. Callers detect missing values via downstream
+ *   required-field checks (a `${VAR}` literal won't satisfy "non-empty string"
+ *   contracts the same way a real key would).
+ * - Non-string values pass through unchanged.
+ */
+/**
+ * Expand a single value: returns `process.env[VAR_NAME]` if `value` is exactly
+ * `${VAR_NAME}` and the env var is defined; returns `value` unchanged otherwise.
+ *
+ * @example
+ * expandEnvVar('${OPENAI_API_KEY}') // process.env.OPENAI_API_KEY or '${OPENAI_API_KEY}' if unset
+ * expandEnvVar('literal')           // 'literal'
+ * expandEnvVar(123)                 // 123
+ * expandEnvVar(undefined)           // undefined
+ */
+export declare function expandEnvVar<T>(value: T): T;
+/**
+ * Recursively expand `${VAR_NAME}` placeholders on every string leaf of a
+ * value. Walks arrays and plain objects; bails on non-plain values.
+ *
+ * Used when a structured config block (e.g. `models.generative.<name>`) has
+ * multiple string fields that may carry env-var placeholders, so callers
+ * don't have to enumerate them.
+ *
+ * @example
+ * expandEnvVarsDeep({ backend: 'openai', apiKey: '${OPENAI_API_KEY}' })
+ * // → { backend: 'openai', apiKey: 'sk-...' }   (if env var set)
+ */
+export declare function expandEnvVarsDeep<T>(value: T): T;
+/**
+ * Returns `true` when `value` is a literal `${VAR_NAME}` placeholder string —
+ * i.e., a value that `expandEnvVar` would have substituted if the env var
+ * were defined but didn't, leaving the original unchanged.
+ *
+ * Useful for distinguishing "operator wrote a literal placeholder by mistake"
+ * (loud, surface to logs) from "operator set the value directly" (proceed).
+ *
+ * @example
+ * isUnresolvedEnvVarPlaceholder('${OPENAI_API_KEY}') // true
+ * isUnresolvedEnvVarPlaceholder('sk-real-key')        // false
+ * isUnresolvedEnvVarPlaceholder('${FOO}-suffix')      // false (partial; not matched by expandEnvVar)
+ */
+export declare function isUnresolvedEnvVarPlaceholder(value: unknown): boolean;

package/dist/utility/expandEnvVar.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Environment-variable expansion for config-loaded values.
+ *
+ * Harper's config parser does not expand `${VAR}` placeholders itself — the
+ * `harperdb-config.yaml` value lands in memory verbatim. Component code that
+ * needs to support env-var indirection (secrets, host overrides, etc.)
+ * applies these helpers to its own config entries.
+ *
+ * The pattern matches the convention established by the OAuth component
+ * (`@harperfast/oauth`'s `src/lib/config.ts`); kept identical so operator
+ * documentation and config snippets carry over verbatim.
+ *
+ * Matching rules:
+ * - Only **whole-string** `${VAR_NAME}` placeholders match. Partial expansion
+ *   (e.g. `'http://${HOST}:9926'`) is NOT supported by design — keeps the
+ *   substitution boundary unambiguous and avoids accidental injection into
+ *   structured values.
+ * - When the env var is undefined, the **original placeholder string is
+ *   returned unchanged**. Callers detect missing values via downstream
+ *   required-field checks (a `${VAR}` literal won't satisfy "non-empty string"
+ *   contracts the same way a real key would).
+ * - Non-string values pass through unchanged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expandEnvVar = expandEnvVar;
+exports.expandEnvVarsDeep = expandEnvVarsDeep;
+exports.isUnresolvedEnvVarPlaceholder = isUnresolvedEnvVarPlaceholder;
+/**
+ * Single shared predicate. Both `expandEnvVar` and `isUnresolvedEnvVarPlaceholder`
+ * must agree on what counts as a placeholder — otherwise an entry can sail past
+ * one check and trip on the other, producing a confusing downstream error.
+ *
+ * A value qualifies when it's a whole-string `${VAR_NAME}` with no internal
+ * whitespace (real shell env-var names disallow whitespace; rejecting it here
+ * means `'${MY KEY}'` is treated as a literal value rather than a botched
+ * lookup that always returns undefined).
+ */
+function looksLikePlaceholder(value) {
+    if (typeof value !== 'string' || !value.startsWith('${') || !value.endsWith('}'))
+        return false;
+    return !value.slice(2, -1).includes(' ');
+}
+/**
+ * Expand a single value: returns `process.env[VAR_NAME]` if `value` is exactly
+ * `${VAR_NAME}` and the env var is defined; returns `value` unchanged otherwise.
+ *
+ * @example
+ * expandEnvVar('${OPENAI_API_KEY}') // process.env.OPENAI_API_KEY or '${OPENAI_API_KEY}' if unset
+ * expandEnvVar('literal')           // 'literal'
+ * expandEnvVar(123)                 // 123
+ * expandEnvVar(undefined)           // undefined
+ */
+function expandEnvVar(value) {
+    if (looksLikePlaceholder(value)) {
+        const envVar = value.slice(2, -1);
+        const envValue = process.env[envVar];
+        // Use the env value when defined (even if empty string — operators may
+        // legitimately want to set an empty default).
+        return (envValue !== undefined ? envValue : value);
+    }
+    return value;
+}
+/**
+ * Recursively expand `${VAR_NAME}` placeholders on every string leaf of a
+ * value. Walks arrays and plain objects; bails on non-plain values.
+ *
+ * Used when a structured config block (e.g. `models.generative.<name>`) has
+ * multiple string fields that may carry env-var placeholders, so callers
+ * don't have to enumerate them.
+ *
+ * @example
+ * expandEnvVarsDeep({ backend: 'openai', apiKey: '${OPENAI_API_KEY}' })
+ * // → { backend: 'openai', apiKey: 'sk-...' }   (if env var set)
+ */
+function expandEnvVarsDeep(value) {
+    if (typeof value === 'string') {
+        return expandEnvVar(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(expandEnvVarsDeep);
+    }
+    if (value !== null && typeof value === 'object') {
+        // `Object.create(null)` avoids prototype-pollution gadgets via a
+        // `__proto__` / `constructor` / `prototype` key. The YAML parser this
+        // helper is initially used against produces plain objects without
+        // these keys, but the helper is documented as reusable; defending
+        // here makes "feed a JSON-from-HTTP payload through this" safe.
+        const expanded = Object.create(null);
+        for (const [key, item] of Object.entries(value)) {
+            expanded[key] = expandEnvVarsDeep(item);
+        }
+        return expanded;
+    }
+    return value;
+}
+/**
+ * Returns `true` when `value` is a literal `${VAR_NAME}` placeholder string —
+ * i.e., a value that `expandEnvVar` would have substituted if the env var
+ * were defined but didn't, leaving the original unchanged.
+ *
+ * Useful for distinguishing "operator wrote a literal placeholder by mistake"
+ * (loud, surface to logs) from "operator set the value directly" (proceed).
+ *
+ * @example
+ * isUnresolvedEnvVarPlaceholder('${OPENAI_API_KEY}') // true
+ * isUnresolvedEnvVarPlaceholder('sk-real-key')        // false
+ * isUnresolvedEnvVarPlaceholder('${FOO}-suffix')      // false (partial; not matched by expandEnvVar)
+ */
+function isUnresolvedEnvVarPlaceholder(value) {
+    return looksLikePlaceholder(value);
+}
+//# sourceMappingURL=expandEnvVar.js.map

package/dist/utility/expandEnvVar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expandEnvVar.js","sourceRoot":"","sources":["../../utility/expandEnvVar.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;AA2BH,oCASC;AAcD,8CAoBC;AAeD,sEAEC;AArFD;;;;;;;;;GASG;AACH,SAAS,oBAAoB,CAAC,KAAc;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/F,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,YAAY,CAAI,KAAQ;IACvC,IAAI,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,uEAAuE;QACvE,8CAA8C;QAC9C,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAM,CAAC;IACzD,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,iBAAiB,CAAI,KAAQ;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAiB,CAAC;IACrD,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACjD,iEAAiE;QACjE,sEAAsE;QACtE,kEAAkE;QAClE,kEAAkE;QAClE,gEAAgE;QAChE,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAA4B,CAAC;QAChE,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YAC5E,QAAQ,CAAC,GAAG,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;QACD,OAAO,QAAa,CAAC;IACtB,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,6BAA6B,CAAC,KAAc;IAC3D,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC"}

package/dist/utility/functions/geo.js

@@ -15,8 +15,8 @@ const turfBooleanEqual = require('@turf/boolean-equal');
 const turfBooleanDisjoint = require('@turf/boolean-disjoint');
 const turfHelpers = require('@turf/helpers');
 const hdbTerms = require("../hdbTerms.js");
-const commonUtils = require('../common_utils.js');
-const hdbLog = require('../logging/harper_logger.js');
+const commonUtils = require("../common_utils.js");
+const hdbLog = require("../logging/harper_logger.js");
 module.exports = {
     geoArea,
     geoLength,

package/dist/utility/functions/sql/alaSQLExtension.js

@@ -6,7 +6,7 @@
 const _ = require('lodash');
 const mathjs = require('mathjs');
 const jsonata = require('jsonata');
-const hdbUtils = require('../../common_utils.js');
+const hdbUtils = require("../../common_utils.js");
 module.exports = {
     /***
      * distinctArray takes in an array an dedupes its values using lodash. this works on complex as well as simple datatypes

package/dist/utility/globalSchema.d.ts

@@ -1,6 +1,7 @@
-export function setSchemaDataToGlobal(callback: any): void;
-export function getTableSchema(schemaName: any, tableName: any, callback: any): any;
-export function getSystemSchema(): {
+export declare const setSchemaDataToGlobalAsync: () => Promise<unknown>;
+export declare function setSchemaDataToGlobal(callback?: any): void;
+export declare function getTableSchema(schemaName: string, tableName: string, callback: any): any;
+export declare function getSystemSchema(): {
     hdb_user: {
         hash_attribute: string;
         name: string;
@@ -147,5 +148,13 @@ export function getSystemSchema(): {
             attribute: string;
         }[];
     };
+    hdb_deployment: {
+        hash_attribute: string;
+        name: string;
+        schema: string;
+        audit: boolean;
+        attributes: {
+            attribute: string;
+        }[];
+    };
 };
-export declare let setSchemaDataToGlobalAsync: () => Promise<any>;

package/dist/utility/globalSchema.js

@@ -1,20 +1,23 @@
 "use strict";
-const systemSchema = require('../json/systemSchema.json');
-const { promisify } = require('util');
-const { getDatabases } = require("../resources/databases.js");
-module.exports = {
-    setSchemaDataToGlobal,
-    getTableSchema,
-    getSystemSchema,
-    setSchemaDataToGlobalAsync: promisify(setSchemaDataToGlobal),
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setSchemaDataToGlobalAsync = void 0;
+exports.setSchemaDataToGlobal = setSchemaDataToGlobal;
+exports.getTableSchema = getTableSchema;
+exports.getSystemSchema = getSystemSchema;
+const systemSchema_json_1 = __importDefault(require("../json/systemSchema.json"));
+const util_1 = require("util");
+const databases_ts_1 = require("../resources/databases.js");
+exports.setSchemaDataToGlobalAsync = (0, util_1.promisify)(setSchemaDataToGlobal);
 function setSchemaDataToGlobal(callback) {
-    global.hdb_schema = getDatabases();
+    global.hdb_schema = (0, databases_ts_1.getDatabases)();
     if (callback)
         callback();
 }
 function getTableSchema(schemaName, tableName, callback) {
-    const database = getDatabases()[schemaName];
+    const database = (0, databases_ts_1.getDatabases)()[schemaName];
     if (!database) {
         return callback(`schema ${schemaName} does not exist`);
     }
@@ -29,6 +32,6 @@ function getTableSchema(schemaName, tableName, callback) {
     });
 }
 function getSystemSchema() {
-    return systemSchema;
+    return systemSchema_json_1.default;
 }
 //# sourceMappingURL=globalSchema.js.map

package/dist/utility/globalSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"globalSchema.js","sourceRoot":"","sources":["../../utility/globalSchema.js"],"names":[],"mappings":";AAAA,MAAM,YAAY,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;AAC1D,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AACtC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;AAE9D,MAAM,CAAC,OAAO,GAAG;IAChB,qBAAqB;IACrB,cAAc;IACd,eAAe;IACf,0BAA0B,EAAE,SAAS,CAAC,qBAAqB,CAAC;CAC5D,CAAC;AAEF,SAAS,qBAAqB,CAAC,QAAQ;IACtC,MAAM,CAAC,UAAU,GAAG,YAAY,EAAE,CAAC;IACnC,IAAI,QAAQ;QAAE,QAAQ,EAAE,CAAC;AAC1B,CAAC;AAED,SAAS,cAAc,CAAC,UAAU,EAAE,SAAS,EAAE,QAAQ;IACtD,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC,UAAU,CAAC,CAAC;IAC5C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,OAAO,QAAQ,CAAC,UAAU,UAAU,iBAAiB,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,QAAQ,CAAC,SAAS,UAAU,IAAI,SAAS,iBAAiB,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,EAAE;QACrB,MAAM,EAAE,UAAU;QAClB,IAAI,EAAE,SAAS;QACf,cAAc,EAAE,KAAK,CAAC,UAAU;KAChC,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe;IACvB,OAAO,YAAY,CAAC;AACrB,CAAC"}
+{"version":3,"file":"globalSchema.js","sourceRoot":"","sources":["../../utility/globalSchema.ts"],"names":[],"mappings":";;;;;;AAMA,sDAGC;AAED,wCAcC;AAED,0CAEC;AA7BD,kFAAqD;AACrD,+BAAiC;AACjC,4DAAyD;AAE5C,QAAA,0BAA0B,GAAG,IAAA,gBAAS,EAAC,qBAAqB,CAAC,CAAC;AAE3E,SAAgB,qBAAqB,CAAC,QAAc;IAClD,MAAc,CAAC,UAAU,GAAG,IAAA,2BAAY,GAAE,CAAC;IAC5C,IAAI,QAAQ;QAAE,QAAQ,EAAE,CAAC;AAC1B,CAAC;AAED,SAAgB,cAAc,CAAC,UAAkB,EAAE,SAAiB,EAAE,QAAa;IAClF,MAAM,QAAQ,GAAG,IAAA,2BAAY,GAAE,CAAC,UAAU,CAAC,CAAC;IAC5C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,OAAO,QAAQ,CAAC,UAAU,UAAU,iBAAiB,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,QAAQ,CAAC,SAAS,UAAU,IAAI,SAAS,iBAAiB,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,EAAE;QACrB,MAAM,EAAE,UAAU;QAClB,IAAI,EAAE,SAAS;QACf,cAAc,EAAE,KAAK,CAAC,UAAU;KAChC,CAAC,CAAC;AACJ,CAAC;AAED,SAAgB,eAAe;IAC9B,OAAO,2BAAY,CAAC;AACrB,CAAC"}

package/dist/utility/hdbTerms.d.ts

@@ -143,6 +143,8 @@ export declare const SYSTEM_TABLE_NAMES: {
     readonly TABLE_TABLE_NAME: "hdb_table";
     readonly USER_TABLE_NAME: "hdb_user";
     readonly INFO_TABLE_NAME: "hdb_info";
+    readonly DEPLOYMENT_TABLE_NAME: "hdb_deployment";
+    readonly AGENT_SESSION_TABLE_NAME: "hdb_agent_session";
 };
 /** Hash attribute for the system info table */
 export declare const INFO_TABLE_HASH_ATTRIBUTE = "info_id";
@@ -259,6 +261,16 @@ export declare const OPERATIONS_ENUM: {
     readonly GET_STATUS: "get_status";
     readonly SET_STATUS: "set_status";
     readonly CLEAR_STATUS: "clear_status";
+    readonly LIST_DEPLOYMENTS: "list_deployments";
+    readonly GET_DEPLOYMENT: "get_deployment";
+    readonly GET_DEPLOYMENT_PAYLOAD: "get_deployment_payload";
+    readonly DELETE_DEPLOYMENT_PAYLOAD: "delete_deployment_payload";
+    readonly AGENT_PROMPT: "agent_prompt";
+    readonly GET_AGENT_SESSION: "get_agent_session";
+    readonly LIST_AGENT_SESSIONS: "list_agent_sessions";
+    readonly CANCEL_AGENT_RUN: "cancel_agent_run";
+    readonly APPROVE_AGENT_ACTION: "approve_agent_action";
+    readonly SET_AGENT_CONFIG: "set_agent_config";
 };
 /** Defines valid file types that we are able to handle in 'import_from_s3' ops */
 export declare const VALID_S3_FILE_TYPES: {
@@ -295,9 +307,12 @@ export declare const SERVICE_ACTIONS_ENUM: {
     readonly UPGRADE: "upgrade";
     readonly HELP: "help";
     readonly STATUS: "status";
+    readonly LOGIN: "login";
+    readonly LOGOUT: "logout";
     readonly OPERATION: "operation";
     readonly RENEWCERTS: "renew-certs";
     readonly COPYDB: "copy-db";
+    readonly MCP: "mcp";
 };
 /** describes the Geo Conversion types */
 export declare const GEO_CONVERSION_ENUM: {
@@ -378,6 +393,8 @@ export declare const LEGACY_CONFIG_PARAMS: {
  */
 export declare const CONFIG_PARAMS: {
     readonly ANALYTICS_AGGREGATEPERIOD: "analytics_aggregatePeriod";
+    readonly ANALYTICS_AGGREGATERETENTIONMS: "analytics_aggregateRetentionMs";
+    readonly ANALYTICS_RAWRETENTIONMS: "analytics_rawRetentionMs";
     readonly ANALYTICS_REPLICATE: "analytics_replicate";
     readonly ANALYTICS_STORAGEINTERVAL: "analytics_storageInterval";
     readonly AUTHENTICATION_AUTHORIZELOCAL: "authentication_authorizeLocal";
@@ -468,6 +485,7 @@ export declare const CONFIG_PARAMS: {
     readonly OPERATIONSAPI_NETWORK_SECUREPORT: "operationsApi_network_securePort";
     readonly OPERATIONSAPI_NETWORK_HTTP2: "operationsApi_network_http2";
     readonly OPERATIONSAPI_NETWORK_MAXREQUESTBODYSIZE: "operationsApi_network_maxRequestBodySize";
+    readonly OPERATIONSAPI_COMPONENTFILE_MAXSIZE: "operationsApi_componentFile_maxSize";
     readonly OPERATIONSAPI_TLS: "operationsApi_tls";
     readonly OPERATIONSAPI_TLS_CERTIFICATE: "operationsApi_tls_certificate";
     readonly OPERATIONSAPI_TLS_PRIVATEKEY: "operationsApi_tls_privateKey";
@@ -475,6 +493,34 @@ export declare const CONFIG_PARAMS: {
     readonly OPERATIONSAPI_NETWORK_TIMEOUT: "operationsApi_network_timeout";
     readonly OPERATIONSAPI_SYSINFO_NETWORK: "operationsApi_sysInfo_network";
     readonly OPERATIONSAPI_SYSINFO_DISK: "operationsApi_sysInfo_disk";
+    readonly MCP_OPERATIONS_MOUNTPATH: "mcp_operations_mountPath";
+    readonly MCP_OPERATIONS_ALLOW: "mcp_operations_allow";
+    readonly MCP_OPERATIONS_DENY: "mcp_operations_deny";
+    readonly MCP_OPERATIONS_MAXTOOLS: "mcp_operations_maxTools";
+    readonly MCP_OPERATIONS_RATELIMIT_PERTOOLPERSECOND: "mcp_operations_rateLimit_perToolPerSecond";
+    readonly MCP_OPERATIONS_RATELIMIT_PERTOOLBURST: "mcp_operations_rateLimit_perToolBurst";
+    readonly MCP_OPERATIONS_RATELIMIT_SESSIONCONCURRENCY: "mcp_operations_rateLimit_sessionConcurrency";
+    readonly MCP_OPERATIONS_RATELIMIT_SESSIONPERSECOND: "mcp_operations_rateLimit_sessionPerSecond";
+    readonly MCP_APPLICATION_MOUNTPATH: "mcp_application_mountPath";
+    readonly MCP_APPLICATION_ALLOW: "mcp_application_allow";
+    readonly MCP_APPLICATION_DENY: "mcp_application_deny";
+    readonly MCP_APPLICATION_MAXTOOLS: "mcp_application_maxTools";
+    readonly MCP_APPLICATION_SEARCHMAXRESULTS: "mcp_application_searchMaxResults";
+    readonly MCP_APPLICATION_RATELIMIT_PERTOOLPERSECOND: "mcp_application_rateLimit_perToolPerSecond";
+    readonly MCP_APPLICATION_RATELIMIT_PERTOOLBURST: "mcp_application_rateLimit_perToolBurst";
+    readonly MCP_APPLICATION_RATELIMIT_SESSIONCONCURRENCY: "mcp_application_rateLimit_sessionConcurrency";
+    readonly MCP_APPLICATION_RATELIMIT_SESSIONPERSECOND: "mcp_application_rateLimit_sessionPerSecond";
+    readonly MCP_SESSION_IDLETIMEOUTSECONDS: "mcp_session_idleTimeoutSeconds";
+    readonly MCP_SESSION_ALLOWCLIENTDELETE: "mcp_session_allowClientDelete";
+    readonly AGENT_ENABLED: "agent_enabled";
+    readonly AGENT_PROVIDER: "agent_provider";
+    readonly AGENT_MODEL: "agent_model";
+    readonly AGENT_MAXTURNS: "agent_maxTurns";
+    readonly AGENT_MAXCOSTUSD: "agent_maxCostUsd";
+    readonly AGENT_AUTOAPPROVE: "agent_autoApprove";
+    readonly AGENT_ALLOWDESTRUCTIVE: "agent_allowDestructive";
+    readonly AGENT_USER: "agent_user";
+    readonly AGENT_COMPONENTSSCOPE: "agent_componentsScope";
     readonly REPLICATION: "replication";
     readonly REPLICATION_HOSTNAME: "replication_hostname";
     readonly REPLICATION_URL: "replication_url";
@@ -501,6 +547,8 @@ export declare const CONFIG_PARAMS: {
     readonly REPLICATION_BLOBCONCURRENCY: "replication_blobConcurrency";
     readonly REPLICATION_MAXPAYLOAD: "replication_maxPayload";
     readonly REPLICATION_RECORDCONCURRENCY: "replication_recordConcurrency";
+    readonly REPLICATION_PINGINTERVAL: "replication_pingInterval";
+    readonly REPLICATION_PINGTIMEOUT: "replication_pingTimeout";
     readonly ROOTPATH: "rootPath";
     readonly SERIALIZATION_BIGINT: "serialization_bigInt";
     readonly STORAGE_WRITEASYNC: "storage_writeAsync";
@@ -529,6 +577,11 @@ export declare const CONFIG_PARAMS: {
     readonly STORAGE_RECLAMATION_INTERVAL: "storage_reclamation_interval";
     readonly STORAGE_RECLAMATION_EVICTIONFACTOR: "storage_reclamation_evictionFactor";
     readonly STORAGE_ENGINE: "storage_engine";
+    readonly STORAGE_READONLY: "storage_readOnly";
+    readonly STORAGE_ROCKS_BLOCKCACHESIZE: "storage_rocks_blockCacheSize";
+    readonly STORAGE_ROCKS_WRITEBUFFERMANAGERSIZE: "storage_rocks_writeBufferManagerSize";
+    readonly STORAGE_ROCKS_WRITEBUFFERMANAGERCOSTTOCACHE: "storage_rocks_writeBufferManagerCostToCache";
+    readonly STORAGE_ROCKS_WRITEBUFFERMANAGERALLOWSTALL: "storage_rocks_writeBufferManagerAllowStall";
     readonly DATABASES: "databases";
     readonly IGNORE_SCRIPTS: "ignoreScripts";
     readonly MQTT_NETWORK_PORT: "mqtt_network_port";
@@ -544,6 +597,7 @@ export declare const CONFIG_PARAMS: {
     readonly TLS_PRIVATEKEY: "tls_privateKey";
     readonly TLS_CERTIFICATEAUTHORITY: "tls_certificateAuthority";
     readonly TLS_CIPHERS: "tls_ciphers";
+    readonly TLS_UNIXDOMAINSOCKETS: "tls_unixDomainSockets";
     readonly TLS: "tls";
     readonly CLONED: "cloned";
     readonly NODE_HOSTNAME: "node_hostname";
@@ -723,6 +777,8 @@ export declare const ITC_EVENT_TYPES: {
     readonly START_JOB: "start_job";
     readonly COMPONENT_STATUS_REQUEST: "component_status_request";
     readonly COMPONENT_STATUS_RESPONSE: "component_status_response";
+    readonly RESOURCE_OPENAPI_REQUEST: "resource_openapi_request";
+    readonly RESOURCE_OPENAPI_RESPONSE: "resource_openapi_response";
 };
 /** Supported thread types */
 export declare const THREAD_TYPES: {