@halix/action-sdk 1.0.38 → 1.0.40

package/lib/esm/payments.js

@@ -0,0 +1,78 @@
+// 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.
+/**
+ * @module @halix/action-sdk/payments
+ * @description Payment completion helpers for the Halix Platform action SDK. This module provides
+ * a wrapper around the `standalonePayment` backend route, which finalizes a payment after a gateway
+ * component has already produced a preauthorization result.
+ *
+ * Typical flow:
+ * 1. Client/UI code collects payment details and obtains a gateway preauth result.
+ * 2. Action code calls `submitStandalonePayment(...)` with the payer, payee, host object, and preauth result.
+ * 3. The platform completes the payment, updates the host object's payment summary field, and optionally
+ *    generates a sales transaction.
+ */
+import axios from 'axios';
+import { from, lastValueFrom } from 'rxjs';
+import { sandboxKey, serviceAddress, getAuthToken, userContext } from './sdk-general';
+const STANDALONE_PAYMENT_URL = 'payments/sandboxes/:sandboxKey/standalonePayment';
+const ASSUMED_PAYER_TYPE = 'SolutionUserProxy';
+const ASSUMED_PAYMENT_GATEWAY = 'stripe';
+const BANK_ACCOUNT_PAYMENT_METHODS = new Set(['us_bank_account', 'USBankAccount', 'bankAccount']);
+function resolveBankAccountPayment(request) {
+    if (request.bankAccountPayment !== undefined) {
+        return request.bankAccountPayment;
+    }
+    return BANK_ACCOUNT_PAYMENT_METHODS.has(request.preAuthResult?.paymentMethod || '');
+}
+function resolveOrganizationKey() {
+    const organizationKey = userContext?.orgKey;
+    if (!organizationKey) {
+        throw new Error('userContext.orgKey is required for standalone payments; check that initialize(event) has been called with a full userContext');
+    }
+    return organizationKey;
+}
+/**
+ * Completes a previously preauthorized standalone payment.
+ *
+ * This endpoint performs the final charge, updates the host object's payment summary attribute,
+ * persists billing address information back to the payer, and can optionally generate a linked
+ * sales transaction.
+ */
+export async function submitStandalonePayment(request) {
+    if (!getAuthToken) {
+        const errorMessage = 'SDK not initialized.';
+        console.error(errorMessage);
+        throw new Error(errorMessage);
+    }
+    const url = `${serviceAddress}/${STANDALONE_PAYMENT_URL.replace(':sandboxKey', sandboxKey)}`;
+    const authToken = await lastValueFrom(getAuthToken());
+    const payload = {
+        ...request,
+        organizationKey: resolveOrganizationKey(),
+        payerType: ASSUMED_PAYER_TYPE,
+        bankAccountPayment: resolveBankAccountPayment(request),
+        preAuthResult: {
+            paymentGateway: ASSUMED_PAYMENT_GATEWAY,
+            ...request.preAuthResult,
+        },
+    };
+    console.log('Sending POST request to ' + url + ' with token ' + authToken);
+    const response = await axios.post(url, payload, {
+        headers: { Authorization: `Bearer ${authToken}` },
+    });
+    return response.data;
+}
+/**
+ * Observable version of submitStandalonePayment. See submitStandalonePayment for details.
+ */
+export function submitStandalonePaymentAsObservable(request) {
+    return from(submitStandalonePayment(request));
+}
+//# sourceMappingURL=payments.js.map

package/lib/esm/payments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payments.js","sourceRoot":"","sources":["../../src/payments.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,mCAAmC;AACnC,EAAE;AACF,oEAAoE;AACpE,0EAA0E;AAC1E,EAAE;AACF,6DAA6D;AAC7D,oDAAoD;AAEpD;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,IAAI,EAAc,aAAa,EAAE,MAAM,MAAM,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEtF,MAAM,sBAAsB,GAAG,kDAAkD,CAAC;AAClF,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAC/C,MAAM,uBAAuB,GAAG,QAAQ,CAAC;AACzC,MAAM,4BAA4B,GAAG,IAAI,GAAG,CAAC,CAAC,iBAAiB,EAAE,eAAe,EAAE,aAAa,CAAC,CAAC,CAAC;AAkElG,SAAS,yBAAyB,CAAC,OAAiC;IAChE,IAAI,OAAO,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;QAC3C,OAAO,OAAO,CAAC,kBAAkB,CAAC;IACtC,CAAC;IAED,OAAO,4BAA4B,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,aAAa,IAAI,EAAE,CAAC,CAAC;AACxF,CAAC;AAED,SAAS,sBAAsB;IAC3B,MAAM,eAAe,GAAG,WAAW,EAAE,MAAM,CAAC;IAE5C,IAAI,CAAC,eAAe,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,8HAA8H,CAAC,CAAC;IACpJ,CAAC;IAED,OAAO,eAAe,CAAC;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,OAAiC;IAC3E,IAAI,CAAC,YAAY,EAAE,CAAC;QAChB,MAAM,YAAY,GAAG,sBAAsB,CAAC;QAC5C,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,cAAc,IAAI,sBAAsB,CAAC,OAAO,CAAC,aAAa,EAAE,UAAU,CAAC,EAAE,CAAC;IAC7F,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,YAAY,EAAE,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG;QACZ,GAAG,OAAO;QACV,eAAe,EAAE,sBAAsB,EAAE;QACzC,SAAS,EAAE,kBAAkB;QAC7B,kBAAkB,EAAE,yBAAyB,CAAC,OAAO,CAAC;QACtD,aAAa,EAAE;YACX,cAAc,EAAE,uBAAuB;YACvC,GAAG,OAAO,CAAC,aAAa;SAC3B;KACJ,CAAC;IAEF,OAAO,CAAC,GAAG,CAAC,0BAA0B,GAAG,GAAG,GAAG,cAAc,GAAG,SAAS,CAAC,CAAC;IAE3E,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE;QAC5C,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,SAAS,EAAE,EAAE;KACpD,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC,IAAI,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mCAAmC,CAAC,OAAiC;IACjF,OAAO,IAAI,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAC;AAClD,CAAC"}

package/lib/esm/types/data-crud.d.ts

@@ -5,7 +5,10 @@ import { Observable } from 'rxjs';
 export interface SaveOptions {
     /** Whether to bypass validation */
     bypassValidation?: boolean;
+    /** Optional relationships to include as nested objects in the saved response */
+    fetchedRelationships?: string[];
 }
+type SaveBody = string | object;
 /**
  * Retrieves a single object by dataElementId and key. Optionally fetch related objects.
  *
@@ -46,20 +49,49 @@ export declare function getAccessibleObjects(dataElementId: string, filter?: str
  */
 export declare function getAccessibleObjectsAsObservable(dataElementId: string, filter?: string, fetchedRelationships?: string[], applyContext?: boolean): Observable<any[]>;
 /**
- * Saves a related object and establishes relationship to parent. Returns saved object with any server-assigned values (objKey, calculated fields).
+ * Retrieves accessible objects for a data element from a specific key list.
+ * Only objects that are accessible to the current user are returned. If applyContext is true, keyed objects outside the current navigation context are also omitted.
+ *
+ * @param dataElementId - Data element ID
+ * @param keys - Object keys to retrieve
+ * @param filter - Optional filter; call `dataexpr_agent` to generate the filter expression. Must be less than 200 characters.
+ * @param fetchedRelationships - Optional relationships to include as nested objects
+ * @param applyContext - Optional flag to apply navigation context scoping. When true, navigation context is read from UserContext.navigationContext and results are limited by the navigation context org proxy.
+ * @returns Promise<any[]>
+ */
+export declare function getObjectsByKeys(dataElementId: string, keys: string[], filter?: string, fetchedRelationships?: string[], applyContext?: boolean): Promise<any[]>;
+/**
+ * Observable version of getObjectsByKeys. See getObjectsByKeys for details.
+ */
+export declare function getObjectsByKeysAsObservable(dataElementId: string, keys: string[], filter?: string, fetchedRelationships?: string[], applyContext?: boolean): Observable<any[]>;
+/**
+ * Saves an object without establishing a parent relationship. Returns saved object with any server-assigned values (objKey, calculated fields).
+ *
+ * @param dataElementId - Data element ID for the object being saved
+ * @param objectToSave - Object data or JSON string of object data
+ * @param opts - Optional save options (e.g., bypassValidation, fetchedRelationships)
+ * @returns Promise<any> - saved object with updates including server-assigned values (objKey, calculated fields)
+ */
+export declare function saveObject(dataElementId: string, objectToSave: SaveBody, opts?: SaveOptions): Promise<any>;
+/**
+ * Observable version of saveObject. See saveObject for details.
+ */
+export declare function saveObjectAsObservable(dataElementId: string, objectToSave: SaveBody, opts?: SaveOptions): Observable<any>;
+/**
+ * Saves a related object and establishes or updates its relationship to a parent. Returns saved object with any server-assigned values (objKey, calculated fields).
  *
  * @param parentElementId - Parent element ID
  * @param parentKey - Parent object key; important: this establishes the scope of the save operation; use an appropriate scope Key
  * @param elementId - Child element ID for the object being saved
- * @param objectToSave - JSON string of object data
- * @param opts - Optional save options (e.g., bypassValidation)
+ * @param objectToSave - Object data or JSON string of object data
+ * @param opts - Optional save options (e.g., bypassValidation, fetchedRelationships)
  * @returns Promise<any> - saved object with updates including server-assigned values (objKey, calculated fields)
  */
-export declare function saveRelatedObject(parentElementId: string, parentKey: string, elementId: string, objectToSave: string, opts?: SaveOptions): Promise<any>;
+export declare function saveRelatedObject(parentElementId: string, parentKey: string, elementId: string, objectToSave: SaveBody, opts?: SaveOptions): Promise<any>;
 /**
  * Observable version of saveRelatedObject. See saveRelatedObject for details.
  */
-export declare function saveRelatedObjectAsObservable(parentElementId: string, parentKey: string, elementId: string, objectToSave: string, opts?: SaveOptions): Observable<any>;
+export declare function saveRelatedObjectAsObservable(parentElementId: string, parentKey: string, elementId: string, objectToSave: SaveBody, opts?: SaveOptions): Observable<any>;
 /**
  * Deletes a single object related to a parent.
  *
@@ -81,3 +113,4 @@ export declare function deleteRelatedObjects(parentElementId: string, parentKey:
  * Observable version of deleteRelatedObjects. See deleteRelatedObjects for details.
  */
 export declare function deleteRelatedObjectsAsObservable(parentElementId: string, parentKey: string, childElementId: string, childKeys: string[]): Observable<boolean>;
+export {};

package/lib/esm/types/index.d.ts

@@ -4,11 +4,12 @@
  * platform. This is the main entry point that provides a unified interface for all SDK functionality.
  */
 export { getAuthToken, sandboxKey, serviceAddress, actionSubject, userContext, params, useBody, initialize, type UserContext, type IncomingEventBody, type BaseActionResponse, type ActionResponse, type NotificationConfig, type ListActionResponse, type FormTemplateActionResponse, type PageTemplateActionResponse, type ObjectSaveActionResponse, type CalculatedFieldActionResponse, type SingleValueActionResponse, type ErrorResponse, prepareSuccessResponse, prepareErrorResponse } from './sdk-general';
-export { type SaveOptions, getObject, getObjectAsObservable, getRelatedObjects, getRelatedObjectsAsObservable, getAccessibleObjects, getAccessibleObjectsAsObservable, saveRelatedObject, saveRelatedObjectAsObservable, deleteRelatedObject, deleteRelatedObjectAsObservable, deleteRelatedObjects, deleteRelatedObjectsAsObservable } from './data-crud';
+export { type SaveOptions, getObject, getObjectAsObservable, getRelatedObjects, getRelatedObjectsAsObservable, getAccessibleObjects, getAccessibleObjectsAsObservable, getObjectsByKeys, getObjectsByKeysAsObservable, saveObject, saveObjectAsObservable, saveRelatedObject, saveRelatedObjectAsObservable, deleteRelatedObject, deleteRelatedObjectAsObservable, deleteRelatedObjects, deleteRelatedObjectsAsObservable } from './data-crud';
 export { type ContentResource, getOrCreateResource, getOrCreateResourceAsObservable, saveResource, saveResourceAsObservable, sendFileContents, sendFileContentsAsObservable, createOrUpdateResource, createOrUpdateResourceAsObservable } from './content';
 export { MessageMethod, type MessageRequest, sendMessage, sendMessageAsObservable } from './messaging';
 export { getUserPreference, getOrganizationPreference, getUserPreferenceAsObservable, getOrganizationPreferenceAsObservable } from './preferences';
 export { type SortField, type DataSortField, type BaseListDataRequest, type PagedListDataRequest, type ListDataResponse, type ListDataOptions, type ListDataSearchOptions, type MassEditValueType, type MassEditRequest, type MassDeleteRequest, type MassChangeResponse, getListData, getListDataAsObservable, massEdit, massEditAsObservable, massDelete, massDeleteAsObservable } from './lists';
 export { AggregationResponse, type AggregationRequest, type AggregationRow, type AggregationGroup, type AggregationSort, type Aggregation, type AggregationGroupTransform, type TransformType, type AggregationType, getAggregateData, getAggregateDataAsObservable } from './data-aggregate';
+export { type GatewayPaymentPreauthResult, type StandalonePaymentRequest, type StandalonePaymentResult, submitStandalonePayment, submitStandalonePaymentAsObservable } from './payments';
 export { type AIRequestOptions, sendAIMessage, sendAIMessageAsObservable } from './ai';
 export { sortObjectArray, compareValues, getValueFromObject, debounceFn } from './utilities';

package/lib/esm/types/lists.d.ts

@@ -40,18 +40,22 @@ export interface BaseListDataRequest {
      * The dataElementId must be related to this through a foreign key or key array.
      * Works with parentKey to scope results. This is often an organization proxy
      * or user proxy element, but not necessarily so.
+     *
+     * Note: in most cases, this can be omitted in which case the system will automatically
+     * return only the records the user can access.
      */
-    parentDataElementId: string;
+    parentDataElementId?: string;
     /**
      * The key of an object that all records must be related to.
      * Works with parentDataElementId to scope results.
      *
-     * Important: this establishes the scope of the query; use an appropriate scope key
+     * Note: in most cases, this can be omitted in which case the system will automatically
+     * return only the records the user can access.
      */
     parentKey?: string;
     /**
      * Optional field to specify the foreign key field on the root element that defines
-     * the relationship to the parent. If omitted, a derived key is assumed.
+     * the relationship to the parent. If omitted, a derived key is assumed. Works with parentDataElementId to scope results.
      */
     parentKeyField?: string;
     /**
@@ -205,11 +209,50 @@ export interface MassChangeResponse {
 /**
  * Retrieves paginated list data. Supports authenticated/public access, filtering, sorting, and binary search.
  *
+ * Common usage:
+ * - For most custom-element list UIs, start with only `dataElementId`, pagination fields,
+ *   and `displayFields`.
+ * - Omit `parentDataElementId` and `parentKey` when you want the records the current user
+ *   can already access.
+ * - Add `parentDataElementId` and `parentKey` only when the list must be anchored to a
+ *   specific parent record.
+ * - Most callers should omit `options`. Use `options.search` only for binary-search
+ *   navigation scenarios, and use `options.bypassTotal` only when you explicitly do not
+ *   need the total count.
+ *
+ * Request shape:
+ * - `dataElementId` (required): root data element to retrieve
+ * - `pageNumber` / `pageSize` (optional): pagination
+ * - `displayFields` (optional): fields to populate in returned objects
+ * - `sort` (optional): sort fields such as `[{ attributeId: 'name' }]`
+ * - `filter` (optional): filter expression
+ * - `parentDataElementId` / `parentKey` (optional): explicit parent scope
+ *
  * @param request - List configuration including dataElementId, parentDataElementId, parentKey, pagination, sort, filter
  * @param options - Optional: isPublic, bypassTotal, search
  * @returns Promise<ListDataResponse> with data array, total count, pageNumber
  *
  * @example
+ * // Most common case: one page of records the current user can access.
+ * const response = await getListData({
+ *   dataElementId: 'student',
+ *   pageNumber: 1,
+ *   pageSize: 10,
+ *   displayFields: ['name', 'studentNumber', 'email', 'grade']
+ * });
+ *
+ * @example
+ * // Custom element pagination with an optional sort.
+ * const response = await getListData({
+ *   dataElementId: 'student',
+ *   pageNumber: currentPage,
+ *   pageSize: 10,
+ *   displayFields: ['name', 'studentNumber', 'email', 'grade'],
+ *   sort: [{ attributeId: 'name' }]
+ * });
+ *
+ * @example
+ * // Explicit parent scoping when the list must be anchored to a specific parent.
  * const listData = await getListData({
  *   dataElementId: 'customer',
  *   parentDataElementId: 'company',
@@ -218,6 +261,24 @@ export interface MassChangeResponse {
  *   pageSize: 50,
  *   displayFields: ['firstName', 'lastName', 'email']
  * });
+ *
+ * @example
+ * // options is rarely needed; omit it unless you need one of these behaviors.
+ * const response = await getListData(
+ *   {
+ *     dataElementId: 'student',
+ *     pageNumber: 1,
+ *     pageSize: 10,
+ *     displayFields: ['name']
+ *   },
+ *   {
+ *     search: {
+ *       attributeId: 'name',
+ *       value: 'Ada',
+ *       total: 100
+ *     }
+ *   }
+ * );
  */
 export declare function getListData(request: PagedListDataRequest, options?: ListDataOptions): Promise<ListDataResponse>;
 /**

package/lib/esm/types/payments.d.ts

@@ -0,0 +1,74 @@
+import { Observable } from 'rxjs';
+/**
+ * Simplified Stripe-oriented gateway preauth result shape accepted by the standalone payment endpoint.
+ *
+ * The SDK assumes Stripe and injects `paymentGateway: 'stripe'` when sending the request. Other gateway-specific
+ * fields may still be required by the backend decoder and payment processor, so unknown additional fields are
+ * preserved and sent through unchanged.
+ */
+export interface GatewayPaymentPreauthResult {
+    /** Billing info captured during payment entry. */
+    userBillingInfo: Record<string, any>;
+    /** Payment method identifier such as `creditCardOrOther` or `us_bank_account`. */
+    paymentMethod?: string;
+    /** Final amount that was preauthorized, including fees when applicable. */
+    totalAmount?: number;
+    /** Additional Stripe preauth data required by the backend, such as token IDs or saved payment method info. */
+    [key: string]: any;
+}
+/**
+ * Request payload for the standalone payment route.
+ *
+ * Notes:
+ * - `organizationKey` is sourced from `userContext.orgKey`.
+ * - `payerType` is assumed to be `SolutionUserProxy`.
+ * - `hostObjectKey`, `hostElementId`, and `hostAttributeId` identify the solution-defined object field that will be
+ *   updated with the returned payment summary when processing completes.
+ */
+export interface StandalonePaymentRequest {
+    /** Payer object key. */
+    payerKey: string;
+    /** Organization key receiving the payment. */
+    payeeKey: string;
+    /** Base payment amount before any processing fee adjustments. */
+    paymentAmount: number;
+    /** Gateway preauthorization result produced by the payment UI flow. */
+    preAuthResult: GatewayPaymentPreauthResult;
+    /**
+     * Whether this payment should be completed as a bank-account/ACH payment.
+     *
+     * If omitted, the SDK infers it from `preAuthResult.paymentMethod` for common ACH method values.
+     */
+    bankAccountPayment?: boolean;
+    /** Key of the host object to update with payment results. */
+    hostObjectKey: string;
+    /** Data element ID of the host object to update with payment results. */
+    hostElementId: string;
+    /** Attribute ID on the host object that must exist in the solution data model to store the payment summary. */
+    hostAttributeId: string;
+    /** If true, the backend also creates a non-POS sales transaction linked to the host object. */
+    generateTransaction?: boolean;
+    /** Optional override for the payment/transaction description. */
+    chargeDescription?: string;
+}
+/**
+ * Result returned by the standalone payment route.
+ */
+export interface StandalonePaymentResult {
+    /** Persisted payment object key. */
+    paymentKey: string;
+    /** User-facing payment summary string written back to the host attribute. */
+    paymentSummary: string;
+}
+/**
+ * Completes a previously preauthorized standalone payment.
+ *
+ * This endpoint performs the final charge, updates the host object's payment summary attribute,
+ * persists billing address information back to the payer, and can optionally generate a linked
+ * sales transaction.
+ */
+export declare function submitStandalonePayment(request: StandalonePaymentRequest): Promise<StandalonePaymentResult>;
+/**
+ * Observable version of submitStandalonePayment. See submitStandalonePayment for details.
+ */
+export declare function submitStandalonePaymentAsObservable(request: StandalonePaymentRequest): Observable<StandalonePaymentResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halix/action-sdk",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "description": "Halix Platform action SDK",
   "types": "./lib/cjs/types/index.d.ts",
   "main": "./lib/cjs/index.js",