@halix/action-sdk 1.0.51 → 1.0.53

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

@@ -1,4 +1,5 @@
 import { Observable } from 'rxjs';
+import type { FilterExpression } from './filter-expression';
 /**
  * SortField is an interface for specifying sort fields.
  */
@@ -64,21 +65,21 @@ export interface BaseListDataRequest {
      */
     childKeysField?: string;
     /**
-     * Filter expression to limit results. Evaluated within the parent key scope.
-     * Call `dataexpr_agent` to generate the filter expression.
-     * Must be less than 200 characters.
+     * Halix filter expression to limit results. Evaluated within the parent key scope.
+     * This is not SQL or JavaScript syntax. Call `build_filter_expression` to generate
+     * the filter expression. Must be less than 200 characters.
      */
-    filter?: string;
+    filter?: FilterExpression;
     /**
-     * List of fields being displayed on the list. Only these fields are populated in
-     * returned objects to reduce payload size. If fields include relationship paths,
-     * those relationships are automatically retrieved.
-     */
-    displayFields?: string[];
-    /**
-     * Additional field values to include that may not be in displayFields, sort, or filters.
+     * Fields to populate in returned rows. If omitted, rows may contain only `objKey`
+     * plus server defaults; every field read from `response.data` should be requested
+     * here. Use this same array for visible fields and fields needed by local
+     * calculations, joins, grouping, charting, sorting, or conditional rendering.
+     *
+     * If fields include relationship paths, those relationships are automatically retrieved.
+     * The SDK sends this to the list service as `displayFields`.
      */
-    additionalFieldsToFetch?: string[];
+    fields?: string[];
 }
 /**
  * PagedListDataRequest extends BaseListDataRequest with pagination properties.
@@ -96,14 +97,26 @@ export interface PagedListDataRequest extends BaseListDataRequest {
 }
 /**
  * ListDataResponse wraps a data provider response to a list data request.
+ *
+ * Rows are returned in the `data` array. Do not read `objects`, `items`, or
+ * the response object itself as the row array. `total` is the total matching
+ * record count across all pages for this request. When `total > data.length`,
+ * the current response is only one page of a larger result set.
  */
-export interface ListDataResponse {
+export interface ListDataResponse<TRecord extends Record<string, unknown> = Record<string, unknown>> {
     /**
-     * A slice of the appropriate runtime struct type containing a single page-worth of data.
-     * The actual type of objects in this array depends on the dataElementId being queried.
+     * A single page of rows for the requested data element. This is the only row array
+     * returned by getListData. Properties such as `objects`, `items`, or `list` are not
+     * part of the SDK response.
+     */
+    data: TRecord[];
+    /**
+     * The total number of matching entries across all pages for this request.
+     * If total is greater than data.length, more pages exist. A caller that is
+     * building a complete report/chart must request additional pages, use an
+     * aggregate endpoint, narrow the query with filters/key lists, or present
+     * the result as a capped/partial view.
      */
-    data: any[];
-    /** The total number of entries across all pages */
     total: number;
     /**
      * The index within the data array of the selected row.
@@ -210,8 +223,14 @@ export interface MassChangeResponse {
  * Retrieves paginated list data. Supports authenticated/public access, filtering, sorting, and binary search.
  *
  * Common usage:
+ * - Use `getListData` when you are building a paged list UI or list-management workflow:
+ *   pagination, explicit totals, server-side sort for the visible list, field projection, search, selection,
+ *   or bulk operations.
+ * - Do not choose `getListData` only because the task is a report. Prefer `getAccessibleObjects`
+ *   for bounded accessible-record reads without list behavior, `getRelatedObjects` when a
+ *   concrete parent key is already known, or `getAggregateData` for grouped counts/sums.
  * - For most custom-element list UIs, start with only `dataElementId`, pagination fields,
- *   and `displayFields`.
+ *   and `fields`.
  * - 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
@@ -219,48 +238,80 @@ export interface MassChangeResponse {
  * - 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.
+ * - Do not use `getListData` as a generic bulk-data loader for reports. Use filtered
+ *   `getAccessibleObjects`, `getRelatedObjects` with a concrete parent key, or `getAggregateData`
+ *   whenever those can answer the data need directly.
+ * - Do not choose `getListData` only because you need a filter. For non-list report/search reads,
+ *   use filtered `getAccessibleObjects`, `getRelatedObjects` with a concrete parent key,
+ *   `getObjects` for explicit key lists, or `getAggregateData`.
+ *
+ * Response shape:
+ * - `response.data` is the row array.
+ * - `response.total` is the total matching record count across all pages when
+ *   requested. If `response.total > response.data.length`, this response is
+ *   a page slice, not the full result set.
+ * - Do not read `response.objects`, `response.items`, or the response object itself as
+ *   the row array.
+ *
+ * Pagination guidance:
+ * - Use `response.total` to decide whether the current page covers the full
+ *   query. For page 1 with pageSize 100 and total 5,000, local aggregation over
+ *   `response.data` covers only the first 100 rows.
+ * - Do not treat a first page or large page as complete report data just because
+ *   it contains rows.
  *
  * Request shape:
  * - `dataElementId` (required): root data element to retrieve
  * - `pageNumber` / `pageSize` (optional): pagination
- * - `displayFields` (optional): fields to populate in returned objects
+ * - `fields` (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
+ * @returns Promise<ListDataResponse<TRecord>> with data array, total count, pageNumber
  *
  * @example
  * // Most common case: one page of records the current user can access.
- * const response = await getListData({
+ * type StudentRow = {
+ *   name: string;
+ *   studentNumber: string;
+ *   email: string;
+ *   grade: string;
+ * };
+ * const response = await getListData<StudentRow>({
  *   dataElementId: 'student',
  *   pageNumber: 1,
  *   pageSize: 10,
- *   displayFields: ['name', 'studentNumber', 'email', 'grade']
+ *   fields: ['name', 'studentNumber', 'email', 'grade']
  * });
+ * const rows = response.data;
  *
  * @example
  * // Custom element pagination with an optional sort.
- * const response = await getListData({
+ * type StudentListRow = { name: string; studentNumber: string; email: string; grade: string };
+ * const response = await getListData<StudentListRow>({
  *   dataElementId: 'student',
  *   pageNumber: currentPage,
  *   pageSize: 10,
- *   displayFields: ['name', 'studentNumber', 'email', 'grade'],
+ *   fields: ['name', 'studentNumber', 'email', 'grade'],
  *   sort: [{ attributeId: 'name' }]
  * });
+ * const rows = response.data;
  *
  * @example
  * // Explicit parent scoping when the list must be anchored to a specific parent.
- * const listData = await getListData({
+ * type CustomerRow = { firstName: string; lastName: string; email: string };
+ * const listData = await getListData<CustomerRow>({
  *   dataElementId: 'customer',
  *   parentDataElementId: 'company',
  *   parentKey: orgProxyKey,
  *   pageNumber: 1,
  *   pageSize: 50,
- *   displayFields: ['firstName', 'lastName', 'email']
+ *   fields: ['firstName', 'lastName', 'email']
  * });
+ * const rows = listData.data;
  *
  * @example
  * // options is rarely needed; omit it unless you need one of these behaviors.
@@ -269,7 +320,7 @@ export interface MassChangeResponse {
  *     dataElementId: 'student',
  *     pageNumber: 1,
  *     pageSize: 10,
- *     displayFields: ['name']
+ *     fields: ['name']
  *   },
  *   {
  *     search: {
@@ -280,7 +331,7 @@ export interface MassChangeResponse {
  *   }
  * );
  */
-export declare function getListData(request: PagedListDataRequest, options?: ListDataOptions): Promise<ListDataResponse>;
+export declare function getListData<TRecord extends Record<string, unknown> = Record<string, unknown>>(request: PagedListDataRequest, options?: ListDataOptions): Promise<ListDataResponse<TRecord>>;
 /**
  * Observable version of getListData. See getListData for details.
  *
@@ -288,7 +339,7 @@ export declare function getListData(request: PagedListDataRequest, options?: Lis
  * getListDataAsObservable({ dataElementId: 'customer', parentDataElementId: 'company', parentKey: orgProxyKey })
  *   .subscribe(response => console.log(response.data));
  */
-export declare function getListDataAsObservable(request: PagedListDataRequest, options?: ListDataOptions): Observable<ListDataResponse>;
+export declare function getListDataAsObservable<TRecord extends Record<string, unknown> = Record<string, unknown>>(request: PagedListDataRequest, options?: ListDataOptions): Observable<ListDataResponse<TRecord>>;
 /**
  * Bulk update multiple records. The dataRequest defines security scope; only records within that scope can be updated.
  * Use valueType 'literal' to set a value, or 'property' to copy from another field.

package/lib/esm/types/sdk-general.d.ts

@@ -103,12 +103,35 @@ export interface NotificationConfig {
     notificationDefinitionId: string;
     /** The key of the organization proxy */
     organizationProxyKey: string;
+    /** The object type of the organization proxy; allows notification dispatch to resolve the owning organization efficiently. */
+    organizationProxyType?: string;
     /** The object type of the data associated with the notification */
     dataObjectType: string;
     /** The key of the data object associated with the notification */
     dataObjectKey: string;
     /** The parameters to pass to the notification */
     params: Record<string, any>;
+    /** Correlates generated notification history with a payment reminder or other producer-owned source. */
+    reminderKey?: string;
+    /** When true, render/log recipients but skip actual channel dispatch and quota tracking. */
+    previewMode?: boolean;
+    /** Outstanding balance copied to generated recipient history rows. */
+    totalOutstandingAmount?: number;
+    /** Per-send email content override. `summary` is used as the email subject. */
+    emailContentOverride?: {
+        summary?: string;
+        content?: string;
+        html?: string;
+    };
+    /** Per-send SMS content override. */
+    smsContentOverride?: {
+        content?: string;
+    };
+    /** Per-send push content override. `summary` is used as the push title. */
+    pushContentOverride?: {
+        summary?: string;
+        content?: string;
+    };
     emailConfig?: {
         /** The type of user proxy to send the email to */
         recipientUserProxyType: string;
@@ -122,6 +145,8 @@ export interface NotificationConfig {
         replyEmailAddress?: string;
         /** The email address to send the email to; use when sending emails to non-user proxies/free-form email addresses; can contain a comma-separated list of email addresses */
         recipientEmail?: string;
+        /** Optional BCC address(es); comma-separated list allowed. Envelope-only. */
+        bccEmail?: string;
     };
     smsConfig?: {
         /** The type of user proxy to send the SMS to */

package/package.json

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