@elliemae/pui-scripting-object 1.55.0 → 1.56.1

package/dist/types/lib/objects/websocket.d.ts

@@ -0,0 +1,211 @@
+import { IEvent } from '../event.js';
+import { IScriptingObject } from '../scriptingObject.js';
+/**
+ * Filter criteria for WebSocket subscription.
+ *
+ * Each key is a filter field name and the value is an array of acceptable values.
+ * Criteria keys are combined with AND logic; multiple values within a key use OR logic.
+ */
+export type SubscriptionFilter = Record<string, string[]>;
+/**
+ * Options for subscribing to a WebSocket resource event.
+ *
+ * Either `resourceId` or `filter` must be provided.
+ */
+export type SubscribeOptions = {
+    /**
+     * Name of the resource to subscribe to (case insensitive).
+     * @example 'serviceOrder'
+     */
+    resource: string;
+    /**
+     * Unique identifier of the specific resource instance to subscribe to.
+     * Cannot be combined with `filter`.
+     * @example '1e65313c-db09-496c-85ba-bb0758623f93'
+     */
+    resourceId?: string;
+    /**
+     * Key/value filter criteria applied against Kafka message headers.
+     * Cannot be combined with `resourceId`.
+     * @example { loanId: ['lo7ee116-ec80-4dbf-b387-14606d0e4807'] }
+     */
+    filter?: SubscriptionFilter;
+};
+/**
+ * Result returned after a successful subscription
+ */
+export type SubscribeResult = {
+    /**
+     * Unique identifier for the active subscription.
+     * Use this to unsubscribe or correlate incoming events.
+     */
+    subscriptionId: string;
+};
+/**
+ * Error detail returned by the WebSocket server
+ */
+export type WebSocketErrorDetail = {
+    /**
+     * Machine-readable error code
+     * @example 'INVALID_RESOURCE'
+     */
+    code: string;
+    /**
+     * Human-readable error message
+     * @example 'Unknown resource name'
+     */
+    message: string;
+};
+/**
+ * Well-known WebSocket command error codes
+ */
+export declare const enum WebSocketErrorCode {
+    PARSING_FAILED = "PARSING_FAILED",
+    MISSING_CORRELATION_ID = "MISSING_CORRELATION_ID",
+    EMPTY_CORRELATION_ID = "EMPTY_CORRELATION_ID",
+    MISSING_TYPE = "MISSING_TYPE",
+    EMPTY_TYPE = "EMPTY_TYPE",
+    INVALID_TYPE = "INVALID_TYPE",
+    MISSING_SUBSCRIPTION_ID = "MISSING_SUBSCRIPTION_ID",
+    EMPTY_SUBSCRIPTION_ID = "EMPTY_SUBSCRIPTION_ID",
+    SUBSCRIPTION_NOT_FOUND = "SUBSCRIPTION_NOT_FOUND",
+    MISSING_RESOURCE = "MISSING_RESOURCE",
+    EMPTY_RESOURCE = "EMPTY_RESOURCE",
+    INVALID_RESOURCE = "INVALID_RESOURCE",
+    MISSING_RESOURCE_ID_AND_FILTER = "MISSING_RESOURCE_ID_AND_FILTER",
+    EMPTY_RESOURCE_ID = "EMPTY_RESOURCE_ID",
+    INVALID_RESOURCE_ID = "INVALID_RESOURCE_ID",
+    INVALID_FILTER_OBJECT = "INVALID_FILTER_OBJECT",
+    EMPTY_FILTER_OBJECT = "EMPTY_FILTER_OBJECT",
+    EMPTY_FILTER_KEY = "EMPTY_FILTER_KEY",
+    INVALID_FILTER_VALUES = "INVALID_FILTER_VALUES",
+    EMPTY_FILTER_VALUES = "EMPTY_FILTER_VALUES",
+    EMPTY_FILTER_VALUE = "EMPTY_FILTER_VALUE"
+}
+/**
+ * Payload delivered with a WebSocket event message
+ */
+export type WebSocketEventMessageInfo = {
+    /**
+     * Subscription that matched this event
+     */
+    subscriptionId: string;
+    /**
+     * Name of the resource that produced the event
+     */
+    resource: string;
+    /**
+     * The event payload forwarded from the server (opaque to the pss gateway)
+     */
+    payload: Record<string, unknown>;
+};
+/**
+ * Event handler for incoming WebSocket event messages.
+ *
+ * Fired when a message matching a subscription's filter criteria is received.
+ * @param params event parameters
+ * @param params.obj websocket object reference
+ * @param params.eventName event name
+ * @param params.eventParams the event message information including subscriptionId, resource, and payload
+ * @param params.eventOptions additional options related to the event
+ */
+export type WebSocketMessageListener = (params: {
+    obj: IWebSocket;
+    eventName: string;
+    eventParams: WebSocketEventMessageInfo;
+    eventOptions?: Record<string, unknown>;
+}) => void;
+/**
+ * Event types available for WebSocket operations.
+ * @see {@link WebSocketMessageListener}
+ */
+export type WebSocketEvents = {
+    /**
+     * Event is fired when a WebSocket event message is received for an active subscription.
+     *
+     * Use {@link WebSocketMessageListener} to handle this event
+     */
+    'websocket.message': WebSocketMessageListener;
+};
+/**
+ * Scripting object for WebSocket communication with the server.
+ *
+ * The microapp host implements this interface and guest microapps use it
+ * to subscribe/unsubscribe to server-side events delivered over WebSocket.
+ *
+ * See {@link WebSocketEvents} for supported events
+ */
+export interface IWebSocket extends IScriptingObject {
+    /**
+     * Event fired when a WebSocket message is received for an active subscription.
+     *
+     * Use {@link WebSocketMessageListener} to handle this event
+     * @example
+     * with v2 SSF
+     * ```ts
+     * guest.subscribe({
+     *   eventId: 'websocket.message',
+     *   callback: ({ eventParams }) => {
+     *     console.log('Received event for subscription', eventParams.subscriptionId);
+     *     console.log('Resource:', eventParams.resource);
+     *     console.log('Payload:', eventParams.payload);
+     *   }
+     * });
+     * ```
+     * @example
+     * with v1 SSF
+     * ```ts
+     * elli.script.subscribe('websocket', 'message', ({ eventParams }) => {
+     *   console.log('Received event for subscription', eventParams.subscriptionId);
+     *   console.log('Resource:', eventParams.resource);
+     *   console.log('Payload:', eventParams.payload);
+     * });
+     * ```
+     */
+    readonly Message: IEvent;
+    /**
+     * Subscribe to a WebSocket resource event.
+     *
+     * Sends a subscribe command to the WebSocket server for the specified resource.
+     * Either `resourceId` or `filter` must be provided in the options.
+     *
+     * On success, returns a {@link SubscribeResult} containing the `subscriptionId`.
+     * If a matching subscription is already active, the existing `subscriptionId` is returned.
+     * The `subscriptionId` is used to correlate incoming event messages and to unsubscribe.
+     * @param options subscription options including resource name, optional resourceId or filter
+     * @returns subscription result containing the unique subscriptionId
+     * @throws error if the resource is unknown or filter/resourceId is invalid
+     * @example
+     * subscribe by resourceId
+     * ```ts
+     * const result = await websocket.subscribe({
+     *   resource: 'serviceOrder',
+     *   resourceId: '1e65313c-db09-496c-85ba-bb0758623f93'
+     * });
+     * console.log('Subscribed with id:', result.subscriptionId);
+     * ```
+     * @example
+     * subscribe by filter
+     * ```ts
+     * const result = await websocket.subscribe({
+     *   resource: 'serviceOrder',
+     *   filter: { loanId: ['lo7ee116-ec80-4dbf-b387-14606d0e4807'] }
+     * });
+     * console.log('Subscribed with id:', result.subscriptionId);
+     * ```
+     */
+    subscribe(options: SubscribeOptions): Promise<SubscribeResult>;
+    /**
+     * Unsubscribe from an active WebSocket subscription.
+     *
+     * Sends an unsubscribe command to the WebSocket server for the given subscriptionId.
+     * After unsubscribing, no further event messages will be received for this subscription.
+     * @param subscriptionId unique identifier of the subscription to cancel
+     * @throws error if the subscriptionId does not exist
+     * @example
+     * ```ts
+     * await websocket.unsubscribe('4fa1ad8a-0ffa-46b5-8871-9b4b4cbf2eb3');
+     * ```
+     */
+    unsubscribe(subscriptionId: string): Promise<void>;
+}

package/dist/types/lib/scriptingObjectEventList.d.ts

@@ -4,9 +4,10 @@ import { FormEvents, IForm } from './objects/form.js';
 import { GlobalEvents, IGlobal } from './objects/global.js';
 import { LoanEvents, ILoan } from './objects/loan.js';
 import { ModuleEvents, IModule } from './objects/module.js';
+import { WebSocketEvents, IWebSocket } from './objects/websocket.js';
 type KeysMatching<T extends object, V> = {
     [K in keyof T]-?: [V] extends [T[K]] ? K : never;
 }[keyof T];
-export type Events = ApplicationEvents & FormEvents & GlobalEvents & LoanEvents & ModuleEvents;
-export type EventObjects = KeysMatching<IApplication, IEvent> | KeysMatching<IForm, IEvent> | KeysMatching<IGlobal, IEvent> | KeysMatching<ILoan, IEvent> | KeysMatching<IModule, IEvent>;
+export type Events = ApplicationEvents & FormEvents & GlobalEvents & LoanEvents & ModuleEvents & WebSocketEvents;
+export type EventObjects = KeysMatching<IApplication, IEvent> | KeysMatching<IForm, IEvent> | KeysMatching<IGlobal, IEvent> | KeysMatching<ILoan, IEvent> | KeysMatching<IModule, IEvent> | KeysMatching<IWebSocket, IEvent>;
 export {};

package/dist/types/lib/scriptingObjectList.d.ts

@@ -12,6 +12,7 @@ import { IMemStorage } from './objects/memStorage.js';
 import { IModule } from './objects/module.js';
 import { IService } from './objects/service.js';
 import { IStyling } from './objects/styling.js';
+import { IWebSocket } from './objects/websocket.js';
 /**
  * list of scripting object names and their types
  */
@@ -30,6 +31,7 @@ export type ScriptingObjectTypes = {
     styling: IStyling;
     transaction: ITransaction;
     transactiontemplate: ITransactionTemplate;
+    websocket: IWebSocket;
 };
 export declare const enum ScriptingObjectNames {
     Analytics = "analytics",
@@ -46,5 +48,6 @@ export declare const enum ScriptingObjectNames {
     Session = "session",
     Styling = "styling",
     Transaction = "transaction",
-    TransactionTemplate = "transactiontemplate"
+    TransactionTemplate = "transactiontemplate",
+    WebSocket = "websocket"
 }