Halix Action SDK

The Halix Action SDK (@halix/action-sdk) provides a development framework for creating NodeJS Lambda-based actions that run inside the Halix Platform. It offers a streamlined API for handling incoming events, interacting with Halix data services, and sending structured responses back to the platform.

📌 Note: This SDK is source-available and is licensed for use only within applications running on the Halix platform.
See the LICENSE file for full terms.

📦 Installation

No installation is required.

The @halix/action-sdk is natively available in the Halix platform runtime and does not need to be manually installed or included via NPM.

Import the SDK using ECMAScript module syntax:

import * as hx from '@halix/action-sdk';

This makes all SDK utilities available under the hx. namespace for clean and consistent access throughout your action logic.

🚀 Getting Started

Here’s a minimal example of a Halix action written in Node.js with ES module syntax:

import * as hx from '@halix/action-sdk';

export const handler = async (event) => {
  // Initialize the SDK with incoming event context
  hx.initialize(event);

  // Get the subject of the action
  const obj = hx.actionSubject;

  // Refresh the object from the server
  let fullObj;
  try {
    fullObj = await hx.getObject('exampleType', obj.objKey);
  } catch (err) {
    console.error('Error fetching object', err);
    return hx.prepareErrorResponse('Failed to retrieve data');
  }

  // Perform updates or logic
  fullObj.status = 'Updated';

  // Save the updated object
  let saved;
  try {
    saved = await hx.saveRelatedObject('parentType', fullObj.parentKey, 'exampleType', fullObj);
  } catch (err) {
    console.error('Error saving object', err);
    return hx.prepareErrorResponse('Failed to save data');
  }

  // Return a success response
  return hx.prepareSuccessResponse({
    responseType: 'formTemplateAction',
    updatedSubject: saved,
    successMessage: 'Object saved successfully',
    isError: false
  });
};

This action pattern is typical for use in Halix’s Lambda-style runtime environment.

📘 Key Concepts

• authToken: Auth token for secure API calls
• sandboxKey: Identifies the current Halix solution environment
• actionSubject: Object being acted on (varies by context)
• userContext: Info about the executing user
• params: Inputs passed to the action

🛠️ Core Functions

| Function | Description | |----------|-------------| | initialize(event) | Initializes the SDK with event context | | getObject(...) / getObjectAsObservable(...) | Retrieve a single object | | getRelatedObjects(...) / getRelatedObjectsAsObservable(...) | Retrieve related objects | | saveRelatedObject(...) / saveRelatedObjectAsObservable(...) | Save objects and relationships | | deleteRelatedObject(...) / deleteRelatedObjectAsObservable(...) | Delete a single related object | | deleteRelatedObjects(...) / deleteRelatedObjectsAsObservable(...) | Delete multiple related objects (uses keys query param) | | prepareSuccessResponse(...) | Create a success response | | prepareErrorResponse(...) | Create an error response |

Notes:

• Functions that interact with services require initialize(event) to have been called; they depend on userContext, sandboxKey, and serviceAddress.

📦 Content Resource Helpers

These helpers simplify working with content resources and file uploads.

| Function | Description | |----------|-------------| | getOrCreateResource(...) / getOrCreateResourceAsObservable(...) | Retrieve an existing content resource by key or create a new one | | saveResource(...) / saveResourceAsObservable(...) | Persist a content resource | | sendFileContents(resourceKey, file, publicFlag) / sendFileContentsAsObservable(...) | Upload file contents (multipart/form-data) to a content resource | | createOrUpdateResource(resourceKey?, file, publicFlag, resourceType, tags) / createOrUpdateResourceAsObservable(...) | Create or update a resource and upload the file in one call |

🧪 Utilities

| Function | Description | |----------|-------------| | getValueFromObject(object, attribute) | Access nested or relationship-based attributes | | debounceFn(fn, wait?) | Debounce utility for throttling calls | | compareValues(a, b, descending, caseInsensitive) | Utility comparer for sorting | | sortObjectArray(array, sort) | Utility to sort object arrays |

🔐 License

Halix SDK License v1.0

This SDK is licensed for use only within applications running on the Halix platform, in accordance with Halix SDK guidelines.

• You may not use this SDK outside the Halix platform.
• Full license text is available in the LICENSE file.

For commercial licensing outside this scope, contact [email protected].

🧰 Contributing

This repository is source-available but not open source. Contributions are currently limited to internal Halix developers and partners. Please open an issue to discuss improvements or bug reports.

🧭 About Halix

Halix is a low-code platform designed to empower developers and business users to build powerful applications quickly. Learn more at halix.io.