@halix/action-sdk 1.0.6 → 1.0.7

package/lib/esm/index.mjs

@@ -1,6 +1,62 @@
-import axios from 'axios';
-export let authToken, sandboxKey, serviceAddress, actionSubject, userContext, params, useBody;
-export async function getRelatedObjects(parentElementId, parentKey, elementId, filter, fetchedRelationships) {
+"use strict";
+// Halix SDK License v1.0
+// Copyright (c) 2025 halix.io LLC.
+//
+// This source code is licensed for use **only** within applications
+// running on the Halix platform, in accordance with Halix SDK guidelines.
+//
+// Unauthorized use outside the Halix platform is prohibited.
+// Full license terms available in the LICENSE file.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useBody = exports.params = exports.userContext = exports.actionSubject = exports.serviceAddress = exports.sandboxKey = exports.authToken = void 0;
+exports.getRelatedObjects = getRelatedObjects;
+exports.getRelatedObjectsAsObservable = getRelatedObjectsAsObservable;
+exports.getObject = getObject;
+exports.getObjectAsObservable = getObjectAsObservable;
+exports.saveRelatedObject = saveRelatedObject;
+exports.saveRelatedObjectAsObservable = saveRelatedObjectAsObservable;
+exports.sortObjectArray = sortObjectArray;
+exports.compareValues = compareValues;
+exports.getValueFromObject = getValueFromObject;
+exports.prepareSuccessResponse = prepareSuccessResponse;
+exports.prepareErrorResponse = prepareErrorResponse;
+exports.initialize = initialize;
+/**
+ * @module @halix/action-sdk
+ * @description Halix Platform action SDK for developing NodeJS Lambda-based actions on the Halix
+ * platform. Defines a framework for accepting incoming events from the Halix platform, making API
+ * requests to the Halix data service, and returning structured action responses back to the Halix
+ * platform.
+ */
+const axios_1 = __importDefault(require("axios"));
+const rxjs_1 = require("rxjs");
+/**
+ * getRelatedObjects retrieves an array of objects from the the database. The objects returned are
+ * related to a parent through a defined relationship in the schema. In a typical setup, action's
+ * auth token must have scope access to the parent object in order to access all of its related
+ * objects.
+ *
+ * It is common to use getRelatedObjects to retrieve all objects belonging to the current user proxy
+ * or organization proxy. For example, in a user context where the current user proxy element is
+ * "customer," an action might want to retrieve all "purchase" objects related to the current
+ * customer. Similarly, in an organization context where the current organization proxy is
+ * "business," an action might want to retrieve all "employee" objects related to the current
+ * business.
+ *
+ * @param parentElementId - The ID of the parent element
+ * @param parentKey - The key of the parent object
+ * @param elementId - The ID of the element
+ * @param filter - Optional filter criteria for the query; if not provided, all related objects will
+ * be returned
+ * @param fetchedRelationships - Optional array of relationships to fetch; if provided, the returned
+ * objects will include the specified related objects as nested objects
+ *
+ * @returns Promise resolving to an array of objects
+ */
+async function getRelatedObjects(parentElementId, parentKey, elementId, filter, fetchedRelationships) {
     let params;
     if (filter || fetchedRelationships) {
         let p = {};
@@ -12,15 +68,50 @@ export async function getRelatedObjects(parentElementId, parentKey, elementId, f
         }
         params = new URLSearchParams(p);
     }
-    let url = `${serviceAddress}/schema/sandboxes/${sandboxKey}/${parentElementId}/${parentKey}/${elementId}`;
-    console.log("Sending GET request to " + url + " with token " + authToken);
-    let response = await axios.get(url, {
-        headers: { "Authorization": `Bearer ${authToken}` },
+    let url = `${exports.serviceAddress}/schema/sandboxes/${exports.sandboxKey}/${parentElementId}/${parentKey}/${elementId}`;
+    console.log("Sending GET request to " + url + " with token " + exports.authToken);
+    let response = await axios_1.default.get(url, {
+        headers: { "Authorization": `Bearer ${exports.authToken}` },
         params: params,
     });
     return response.data;
 }
-export async function getObject(dataElementId, key, fetchedRelationships) {
+/**
+ * getRelatedObjectsAsObservable retrieves an array of objects from the the database. The objects
+ * returned are related to a parent through a defined relationship in the schema. In a typical
+ * setup, action's auth token must have scope access to the parent object in order to access all of
+ * its related objects.
+ *
+ * It is common to use getRelatedObjects to retrieve all objects belonging to the current user proxy
+ * or organization proxy. For example, in a user context where the current user proxy element is
+ * "customer," an action might want to retrieve all "purchase" objects related to the current
+ * customer. Similarly, in an organization context where the current organization proxy is
+ * "business," an action might want to retrieve all "employee" objects related to the current
+ * business.
+ *
+ * @param parentElementId - The ID of the parent element
+ * @param parentKey - The key of the parent element
+ * @param elementId - The ID of the element
+ * @param filter - Optional filter criteria for the query; if not provided, all related objects will
+ * be returned
+ * @param fetchedRelationships - Optional array of relationships to fetch; if provided, the returned
+ * objects will include the specified related objects as nested objects
+ *
+ * @returns Observable resolving to an array of objects
+ */
+function getRelatedObjectsAsObservable(parentElementId, parentKey, elementId, filter, fetchedRelationships) {
+    return (0, rxjs_1.from)(getRelatedObjects(parentElementId, parentKey, elementId, filter, fetchedRelationships));
+}
+/**
+ * getObject retrieves a single object from the database by its data element ID and key.
+ *
+ * @param dataElementId - The ID of the data element
+ * @param key - The key of the object
+ * @param fetchedRelationships - Optional array of relationships to fetch; if provided, the returned
+ * object will include the specified related objects as nested objects
+ * @returns Promise resolving to the object data
+ */
+async function getObject(dataElementId, key, fetchedRelationships) {
     let params;
     if (fetchedRelationships) {
         let p = {};
@@ -29,30 +120,83 @@ export async function getObject(dataElementId, key, fetchedRelationships) {
         }
         params = new URLSearchParams(p);
     }
-    let url = `${serviceAddress}/schema/sandboxes/${sandboxKey}/${dataElementId}/${key}`;
-    console.log("Sending GET request to " + url + " with token " + authToken);
-    let response = await axios.get(url, {
-        headers: { "Authorization": `Bearer ${authToken}` },
+    let url = `${exports.serviceAddress}/schema/sandboxes/${exports.sandboxKey}/${dataElementId}/${key}`;
+    console.log("Sending GET request to " + url + " with token " + exports.authToken);
+    let response = await axios_1.default.get(url, {
+        headers: { "Authorization": `Bearer ${exports.authToken}` },
         params: params,
     });
     return response.data;
 }
-export async function saveRelatedObject(parentElementId, parentKey, elementId, objectToSave, opts) {
-    let url = `${serviceAddress}/schema/sandboxes/${sandboxKey}/${parentElementId}/${parentKey}/${elementId}`;
+/**
+ * getObjectAsObservable retrieves a single object from the database by its data element ID and key.
+ *
+ * @param dataElementId - The ID of the data element
+ * @param key - The key of the object
+ * @param fetchedRelationships - Optional array of relationships to fetch; if provided, the returned
+ * object will include the specified related objects as nested objects
+ *
+ * @returns Observable resolving to the object data
+ */
+function getObjectAsObservable(dataElementId, key, fetchedRelationships) {
+    return (0, rxjs_1.from)(getObject(dataElementId, key, fetchedRelationships));
+}
+/**
+ * saveRelatedObject saves a related object to the database. The objectToSave is saved, and its
+ * relationship to the parent object is established based on the relationship specified in the
+ * schema. The objectToSave must have a relationship to the parent object and the user must have
+ * scope access to the parent object.
+ *
+ * @param parentElementId - The ID of the parent element
+ * @param parentKey - The key of the parent object
+ * @param elementId - The element ID of the object to save
+ * @param objectToSave - The object data to save (as a JSON string)
+ * @param opts - Optional save options
+ *
+ * @returns Promise resolving to saved object, including any updates made to the object during the
+ * save operation (such as assigning an objKey if the object is new), or the assignment of
+ * calculated values
+ */
+async function saveRelatedObject(parentElementId, parentKey, elementId, objectToSave, opts) {
+    let url = `${exports.serviceAddress}/schema/sandboxes/${exports.sandboxKey}/${parentElementId}/${parentKey}/${elementId}`;
     if (opts?.bypassValidation) {
         url += "?bypassValidation=true";
     }
-    console.log("Sending POST request to " + url + " with token " + authToken);
-    let response = await axios.post(url, objectToSave, {
-        headers: { "Authorization": `Bearer ${authToken}` },
+    console.log("Sending POST request to " + url + " with token " + exports.authToken);
+    let response = await axios_1.default.post(url, objectToSave, {
+        headers: { "Authorization": `Bearer ${exports.authToken}` },
     });
     return response.data;
 }
-/*
- * Sorts the passed array in place by the given attributes. Sorting by nested attributes in the form of a delimited
- * attribute string are supported (e.g., "attribute.nestedAttribute").
+/**
+ * saveRelatedObjectAsObservable saves a related object to the database. The objectToSave is saved,
+ * and its relationship to the parent object is established based on the relationship specified in
+ * the schema. The objectToSave must have a relationship to the parent object and the user must have
+ * scope access to the parent object.
+ *
+ * @param parentElementId - The ID of the parent element
+ * @param parentKey - The key of the parent object
+ * @param elementId - The element ID of the object to save
+ * @param objectToSave - The object data to save (as a JSON string)
+ * @param opts - Optional save options
+ *
+ * @returns Observable resolving to saved object, including any updates made to the object during
+ * the save operation (such as assigning an objKey if the object is new), or the assignment of
+ * calculated values
  */
-export function sortObjectArray(array, sort) {
+function saveRelatedObjectAsObservable(parentElementId, parentKey, elementId, objectToSave, opts) {
+    return (0, rxjs_1.from)(saveRelatedObject(parentElementId, parentKey, elementId, objectToSave, opts));
+}
+/**
+ * sortObjectArray is a helper function that sorts the passed array in place by the given
+ * attributes. Sorting by nested attributes in the form of a delimited attribute string are
+ * supported (e.g., "attribute.nestedAttribute").
+ *
+ * @param array - The array to sort
+ * @param sort - Array of sort field specifications
+ * @returns The sorted array
+ */
+function sortObjectArray(array, sort) {
     return array.sort((a, b) => {
         let comparison = 0;
         for (let s of sort) {
@@ -66,7 +210,19 @@ export function sortObjectArray(array, sort) {
         return comparison;
     });
 }
-export function compareValues(valueA, valueB, descending, caseInsensitive) {
+/**
+ * compareValues is a helper function that compares two values for sorting purposes. If the values
+ * are strings, the comparison is case-insensitive. If the values are numbers, the comparison is
+ * performed numerically.
+ *
+ * @param valueA - First value to compare
+ * @param valueB - Second value to compare
+ * @param descending - Whether to sort in descending order
+ * @param caseInsensitive - Whether to perform case-insensitive comparison for strings
+ *
+ * @returns Comparison result (-1, 0, or 1)
+ */
+function compareValues(valueA, valueB, descending, caseInsensitive) {
     if (caseInsensitive && (typeof valueA === 'string' || valueA instanceof String)) {
         if (valueA && valueB) {
             let comp = valueA.toLowerCase().localeCompare(valueB.toLowerCase());
@@ -95,7 +251,20 @@ export function compareValues(valueA, valueB, descending, caseInsensitive) {
     }
     return 0;
 }
-export function getValueFromObject(object, attribute) {
+/**
+ * getValueFromObject is a helper function that extracts a value from an object using a dot-notation
+ * path. The path can include relationships. Relationship IDs may include a colon delimiter (e.g.,
+ * "accountMember:ownerAccountMemberKey") to specify the key of the related object. This is useful
+ * when an element has more than one relationship to the same object type. Otherwise, if only one
+ * relationship to the same object type exists, the key may be specified without the relationship ID
+ * (e.g., simply, "accountMember").
+ *
+ * @param object - The object to extract value from
+ * @param attribute - The attribute path (e.g., "user.address.city")
+ *
+ * @returns The extracted value
+ */
+function getValueFromObject(object, attribute) {
     let components = attribute.split(".");
     let value = object;
     for (let component of components) {
@@ -116,17 +285,37 @@ export function getValueFromObject(object, attribute) {
     }
     return value;
 }
-export function prepareSuccessResponse(returnVal) {
-    if (useBody) {
+/**
+ * prepareSuccessResponse prepares a success response in the appropriate format. The action handler
+ * should return an ActionResponse response when the action is successful. If useBody is true, the
+ * response will be returned as an object with the HTTP response code and the ActionResponse in the
+ * body field. If useBody is false, the ActionResponse will be returned directly.
+ *
+ * @param successResponse - The value to return
+ *
+ * @returns Formatted success response; an ActionResponse unless useBody is true
+ */
+function prepareSuccessResponse(successResponse) {
+    if (exports.useBody) {
         return {
             statusCode: 200,
-            body: JSON.stringify(returnVal)
+            body: JSON.stringify(successResponse)
         };
     }
-    return returnVal;
+    return successResponse;
 }
-export function prepareErrorResponse(errorMessage) {
-    if (useBody) {
+/**
+ * prepareErrorResponse prepares an error response in the appropriate format. The action handler
+ * should return an ErrorResponse response when the action is not successful. If useBody is true,
+ * the response will be returned as an object with the HTTP response code and the ErrorResponse in
+ * the body field. If useBody is false, the ErrorResponse will be returned directly.
+ *
+ * @param errorMessage - The error message
+ *
+ * @returns Formatted error response; an ErrorResponse unless useBody is true
+ */
+function prepareErrorResponse(errorMessage) {
+    if (exports.useBody) {
         return {
             statusCode: 400,
             body: JSON.stringify({ errorMessage })
@@ -134,11 +323,20 @@ export function prepareErrorResponse(errorMessage) {
     }
     return { errorMessage, responseType: "error" };
 }
-export function initialize(event) {
+/**
+ * initialize initializes the SDK with event data. This should be called at the beginning of the
+ * action handler to set up the SDK with incoming information, including context information, input
+ * parameters, and authentication information needed to make API requests to the Halix service.
+ *
+ * @param event - The event object containing authentication and context information
+ */
+function initialize(event) {
     let body = event;
     if (event.body) {
         body = event.body;
-        useBody = true;
+        exports.useBody = true;
+    }
+    if (body) {
+        ({ authToken: exports.authToken, sandboxKey: exports.sandboxKey, serviceAddress: exports.serviceAddress, actionSubject: exports.actionSubject, userContext: exports.userContext, params: exports.params } = body);
     }
-    ({ authToken, sandboxKey, serviceAddress, actionSubject, userContext, params } = body);
 }