@or-sdk/hitl 0.35.2-beta.3703.0 → 0.35.2-beta.3708.0

package/src/api/Agents.ts

@@ -21,6 +21,19 @@ import {
 
 import { HITLBase } from './HITLBase';
 
+/**
+ * Manages HitL (Human-in-the-Loop) agents in the system
+ *
+ * This class provides functionality:
+ * - retrieve and search agents,
+ * - manage agents permissions, status and additional meta information
+ *
+ * @remarks
+ * - All methods in this class interact with the `/agents` endpoint
+ * - For methods getAgentStatus, setAgentStatus and updateAgentsStatusByQuery need to use { version: 2 }
+ *
+ * @public
+ */
 export class Agents extends HITLBase {
   protected static MODULE_URL = 'agents';
   protected static AGENT_SEARCH_URL = 'search';
@@ -44,6 +57,7 @@ export class Agents extends HITLBase {
    * - `orderBy` - (Optional, string) Field name to order the results by
    * - `order` - (Optional, 'asc'|'desc') Order direction
    * - `version` - (Optional, number) API version
+   * - `timeout` - (Optional, number) Search timeout in milliseconds
    *
    * @returns {Promise<GetAgentsResponse>} Promise resolving to:
    * - `data` - Array of partial agent objects {@link Agent}
@@ -53,7 +67,7 @@ export class Agents extends HITLBase {
    *
    * @example
    * ```typescript
-   * const response = await Agents.getAgents({
+   * const response = await hitlApi.agents.getAgents({
    *   limit: 10,
    *   offset: 0,
    *   orderBy: 'createdAt',
@@ -64,7 +78,7 @@ export class Agents extends HITLBase {
    * @example
    * Using projection and filtering by specific agents:
    * ```typescript
-   * const response = await Agents.getAgents({
+   * const response = await hitlApi.agents.getAgents({
    *   agentIds: ['agent1', 'agent2'],
    *   projection: ['id', 'name', 'statusData'],
    *   orderBy: 'name',
@@ -107,7 +121,7 @@ export class Agents extends HITLBase {
    *
    * @example
    * ```typescript
-   * const response = await Agents.getCompleteAgents();
+   * const response = await hitlApi.agents.getCompleteAgents();
    * ```
    *
    * @remarks
@@ -144,7 +158,7 @@ export class Agents extends HITLBase {
    *
    * @example
    * ```typescript
-   * const agent = await Agents.getCompleteAgentById({
+   * const agent = await hitlApi.agents.getCompleteAgentById({
    *   agentId: 'agent-id',
    *   multiUserId: 'multi456'
    * });
@@ -193,7 +207,7 @@ export class Agents extends HITLBase {
    *
    * @example
    * ```typescript
-   * const response = await Agents.searchAgents({
+   * const response = await hitlApi.agents.searchAgents({
    *   ruleGroupIds: ['group1', 'group2'],
    *   statuses: ['AVAILABLE', 'BUSY'],
    *   projection: ['id', 'name', 'statusData']
@@ -238,7 +252,7 @@ export class Agents extends HITLBase {
    *
    * @example
    * ```typescript
-   * const updatedAgent = await Agents.updateAgent({
+   * const updatedAgent = await hitlApi.agents.updateAgent({
    *   agentId: 'agent-id',
    *   ruleGroupIds: ['group1', 'group2'],
    *   meta: {
@@ -284,7 +298,7 @@ export class Agents extends HITLBase {
    *
    * @example
    * ```typescript
-   * const updatedAgent = await Agents.updateAgentRuleGroups({
+   * const updatedAgent = await hitlApi.agents.updateAgentRuleGroups({
    *   agentId: 'agent-id',
    *   addRuleGroupIds: ['group1', 'group2'],
    *   removeRuleGroupIds: ['group3', 'group4']
@@ -327,7 +341,7 @@ export class Agents extends HITLBase {
    *
    * @example
    * ```typescript
-   * const status = await Agents.getAgentStatus({
+   * const status = await hitlApi.agents.getAgentStatus({
    *   agentId: 'agent-id',
    *   version: 2
    * });
@@ -368,7 +382,7 @@ export class Agents extends HITLBase {
    *
    * @example
    * ```typescript
-   * const status = await Agents.pingAgentStatus();
+   * const status = await hitlApi.agents.pingAgentStatus();
    * ```
    *
    * @remarks
@@ -409,7 +423,7 @@ export class Agents extends HITLBase {
    *
    * @example
    * ```typescript
-   * await Agents.setAgentStatus({
+   * await hitlApi.agents.setAgentStatus({
    *   agentId: 'agent-id',
    *   statusData: {
    *     key: 'busy',
@@ -466,7 +480,7 @@ export class Agents extends HITLBase {
    *
    * @example
    * ```typescript
-   * const result = await Agents.updateAgentsStatusByQuery({
+   * const result = await hitlApi.agents.updateAgentsStatusByQuery({
    *   query: `UPDATE hitl.agents SET status_data = jsonb_set(status_data, '{key}', '"busy"') WHERE status_data->>'key'='available' RETURNING*`,
    *   maxRetries: 5,
    *   version: 2

package/src/api/CannedMessages.ts

@@ -10,19 +10,76 @@ import {
 
 import { HITLBase } from './HITLBase';
 
+/**
+ * Manages canned messages (predefined message templates) in the system
+ *
+ * This class provides functionality to create, retrieve, update, and delete canned messages.
+ * Canned messages are predefined templates that can be used for quick responses in various scenarios.
+ *
+ * Key features:
+ * - Manage message templates with categories and labels
+ * - Support for common (shared) messages across agents
+ * - Attachment handling capabilities
+ * - Rule-based tagging system
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * // Get all canned messages
+ * const messages = await hitlApi.сannedMessages.getCannedMessages();
+ *
+ * // Create a new template
+ * const newTemplate = await hitlApi.сannedMessages.createCannedMessage({
+ *   category: 'greeting',
+ *   text: 'Hello! How can I help you today?',
+ *   isCommon: true
+ * });
+ * ```
+ *
+ * @remarks
+ * - All methods in this class interact with the `/canned-messages` endpoint
+ * - Available only { version: 1 } of API
+ * @public
+ */
 export class CannedMessages extends HITLBase {
   protected static MODULE_URL = 'canned-messages';
 
   /**
-   * @description Get a list of Canned Messages (Message templates)
-   * @param options
+   * Gets a list of canned messages (message templates)
+   *
+   * @param options - Configuration options for the canned messages list request
+   *
+   * Options can include:
+   * - `agentId` - (Optional, string) Filter messages by specific agent
+   * - `categories` - (Optional, string[]) Filter by message categories
+   * - `id` - (Optional, string) Get specific message by ID
+   * - `ignoreRuleTags` - (Optional, boolean) Whether to ignore rule tags in filtering
+   * - `isCommon` - (Optional, boolean) Filter by system or personal message status
+   * - `timeout` - (Optional, number) Request timeout in milliseconds
+   * - `version` - (Optional, string | number) API version to use
+   *
+   * @returns {Promise<GetCannedMessagesResponse | CannedMessage>} Promise resolving to:
+   * - `data` - Array of canned message objects {@link CannedMessage}
+   *
+   * @example
+   * ```typescript
+   * const response = await hitlApi.сannedMessages.getCannedMessages({
+   *   categories: ['support', 'greeting'],
+   *   isCommon: true,
+   *   agentId: 'agent123'
+   * });
+   * ```
+   *
+   * @remarks
+   * Makes a GET request to the `/canned-messages` endpoint
+   * @public
    */
   public static async getCannedMessages(
-    options: GetCannedMessagesOptions = {}
+    options: GetCannedMessagesOptions = {},
   ): Promise<GetCannedMessagesResponse | CannedMessage> {
     const route = this.getBaseUrl(options);
     const params = Object.fromEntries(
-      Object.entries(options).filter(([key]) => !DEFAULT_OMIT_FIELDS.includes(key))
+      Object.entries(options).filter(([key]) => !DEFAULT_OMIT_FIELDS.includes(key)),
     );
 
     return this.request({
@@ -33,17 +90,52 @@ export class CannedMessages extends HITLBase {
     });
   }
 
-
   /**
-   * @description Create Canned Message (Message template)
-   * @param options
+   * Creates a new canned message (message template)
+   *
+   * @param options - Configuration options for creating the canned message
+   *
+   * Required options:
+   * - `category` - (string) Category of the message
+   * - `text` - (string) Content of the message
+   *
+   * Optional options:
+   * - `agentId` - (Optional, string) ID of the agent to associate with
+   * - `attachments` - (Optional, CannedMessageAttachment[]) Array of attachments
+   * - `isCommon` - (Optional, boolean) Whether the message is system or pesronal
+   * - `label` - (Optional, string) Label for the message
+   * - `ruleTags` - (Optional, string[]) Array of rule tags
+   * - `timeout` - (Optional, number) Request timeout in milliseconds
+   * - `version` - (Optional, string | number) API version to use
+   *
+   * @returns {Promise<CannedMessage>} Promise resolving to the created canned message
+   *
+   * @example
+   * ```typescript
+   * const newMessage = await hitlApi.сannedMessages.createCannedMessage({
+   *   category: 'support',
+   *   text: "Thank you for your patience!",
+   *   label: "Thank You Response",
+   *   isCommon: true,
+   *   ruleTags: ['greeting', 'sms'],
+   *   attachments: [
+   *     {
+   *       "key": "IMAGE.JPG"
+   *     }
+   *   ]
+   * });
+   * ```
+   *
+   * @remarks
+   * Makes a POST request to the `/canned-messages` endpoint
+   * @public
    */
   public static async createCannedMessage(
-    { isCommon, agentId, ...options }: CreateCannedMessageOptions
+    { isCommon, agentId, ...options }: CreateCannedMessageOptions,
   ): Promise<CannedMessage> {
     const route = this.getBaseUrl(options);
     const data = Object.fromEntries(
-      Object.entries(options).filter(([key]) => !DEFAULT_OMIT_FIELDS.includes(key))
+      Object.entries(options).filter(([key]) => !DEFAULT_OMIT_FIELDS.includes(key)),
     );
 
     return this.request({
@@ -58,17 +150,54 @@ export class CannedMessages extends HITLBase {
     });
   }
 
-
   /**
-   * @description Update Canned Message (Message template)
-   * @param options
+   * Updates an existing canned message (message template)
+   *
+   * @param options - Configuration options for updating the canned message
+   *
+   * Required options:
+   * - `id` - (string) Unique identifier of the message to update
+   *
+   * Optional update fields:
+   * - `attachments` - (Optional, CannedMessageAttachment[]) Array of attachments
+   * - `category` - (Optional, string) New category for the message
+   * - `label` - (Optional, string) New label for the message
+   * - `ruleTags` - (Optional, string[]) New array of rule tags
+   * - `text` - (Optional, string) New content of the message
+   * - `timeout` - (Optional, number) Request timeout in milliseconds
+   * - `version` - (Optional, string | number) API version to use
+   *
+   * System fields (automatically managed):
+   * - `createdAt` - (Optional, Date) Creation timestamp
+   * - `updatedAt` - (Optional, Date) Last update timestamp
+   *
+   * @returns {Promise<CannedMessage>} Promise resolving to the updated canned message
+   *
+   * @example
+   * ```typescript
+   * const updatedMessage = await hitlApi.сannedMessages.updateCannedMessage({
+   *   id: "msg123",
+   *   text: "Updated response text",
+   *   category: "support",
+   *   ruleTags: ['sms', 'admin'],
+   *   attachments: [
+   *     {
+   *       "key": "IMAGE_2.JPG"
+   *     }
+   *   ]
+   * });
+   * ```
+   *
+   * @remarks
+   * Makes a PUT request to the `/canned-messages` endpoint
+   * @public
    */
   public static async updateCannedMessage(
-    options: UpdateCannedMessageOptions
+    options: UpdateCannedMessageOptions,
   ): Promise<CannedMessage> {
     const route = this.getBaseUrl(options);
     const data = Object.fromEntries(
-      Object.entries(options).filter(([key]) => !DEFAULT_OMIT_FIELDS.includes(key))
+      Object.entries(options).filter(([key]) => !DEFAULT_OMIT_FIELDS.includes(key)),
     );
 
     return this.request({
@@ -80,12 +209,32 @@ export class CannedMessages extends HITLBase {
   }
 
   /**
-   * @description Delete Canned Message (Message template)
-   * @param options
+   * Deletes a canned message (message template)
+   *
+   * @param options - Configuration options for deleting the canned message
+   *
+   * Required options:
+   * - `id` - (string) Unique identifier of the message to delete
+   *
+   * Optional options:
+   * - `version` - (Optional, string | number) API version to use
+   * - `timeout` - (Optional, number) Request timeout in milliseconds
+   *
+   * @returns {Promise<void>} Promise that resolves when deletion is complete
+   *
+   * @example
+   * ```typescript
+   * await hitlApi.сannedMessages.deleteCannedMessage({
+   *   id: "msg123"
+   * });
+   * ```
+   *
+   * @remarks
+   * Makes a DELETE request to the `/canned-messages` endpoint
+   * @public
    */
-
   public static async deleteCannedMessage(
-    { id, ...options }: DeleteCannedMessageOptions
+    { id, ...options }: DeleteCannedMessageOptions,
   ): Promise<void> {
     const route = this.getBaseUrl(options);
 

package/src/api/Commands.ts

@@ -2,15 +2,55 @@ import { ApplyCommandOptions } from '../types/commands';
 
 import { HITLBase } from './HITLBase';
 
+/**
+ * Manages command operations in the HitL (Human-in-the-Loop) system
+ *
+ * This class provides functionality to send and manage commands within HitL sessions,
+ * allowing control and interaction with conversations or processes.
+ *
+ * @remarks
+ * - All methods in this class interact with the `/commands` endpoint
+ * - Available only { version: 1 } of API
+ *
+ * @public
+ */
 export class Commands extends HITLBase {
   protected static MODULE_URL = 'commands';
 
   /**
-   * @description Send a Command to the flow currently in control of the HitL Session
-   * @param options
+   * Sends a command to the flow currently controlling the HitL session
+   *
+   * This method allows sending specific commands to modify or control the behavior
+   * of HitL session. The command is processed by the flow subscription
+   * of the specified session.
+   *
+   * @param options - Configuration options for the command
+   *
+   * Options can include:
+   * - `command` - (Required, string) The command to be executed in the session
+   * - `sessionId` - (Required, string) ID of the target HITL session
+   * - `data` - (Required, object) Command-specific payload containing parameters for execution
+   * - `version` - (Optional, number) API version to use for the request
+   * - `timeout` - (Optional, number) Request timeout in milliseconds
+   *
+   * @returns Promise<void> that resolves when the command is successfully applied
+   *
+   * @example
+   * ```typescript
+   * await hitlApi.commands.applyCommandToSession({
+   *   command: 'send_message',
+   *   sessionId: 'session-id',
+   *   data: {
+   *     media: [],
+   *     text: 'hello world'
+   *   }
+   * });
+   * ```
+   *
+   * @public
    */
   public static async applyCommandToSession(
-    { command, sessionId, data, ...options }: ApplyCommandOptions
+    { command, sessionId, data, ...options }: ApplyCommandOptions,
   ): Promise<void> {
     const route = this.getBaseUrl(options);
 

package/src/api/Conferences.ts

@@ -1,23 +1,86 @@
 import {
   GetConferenceMembersOptions,
   GetConferenceMembersResponse,
-  Conference,
+  ConferenceMember,
   AddOrUpdateConferenceMemberOptions,
   CleanUpConferenceOptions,
 } from '../types/conferences';
 
 import { HITLBase } from './HITLBase';
 
+/**
+ * Manages conference members and their interactions in the system
+ *
+ * This class provides functionality to manage conference participants, including retrieving,
+ * adding, updating, and removing conference members.
+ *
+ * Key features:
+ * - Manage conference member states and statuses
+ * - Handle member identifiers and types
+ * - Track member connection states
+ * - Support for cleanup operations
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * // Get conference members
+ * const members = await hitlApi.conferences.getConferenceMembers({
+ *   hitlSessionId: 'session123'
+ * });
+ *
+ * // Add a new conference member
+ * const newMember = await hitlApi.conferences.addOrUpdateConferenceMember({
+ *   hitlSessionId: 'session123',
+ *   type: 'participant',
+ *   identifier: 'user456'
+ * });
+ * ```
+ *
+ * @remarks
+ * - All methods in this class interact with the `/conferences` endpoint
+ * - Supports HITL (Human-In-The-Loop) session management
+ * @public
+ */
 export class Conferences extends HITLBase {
   protected static MODULE_URL = 'conferences';
 
   /**
-   * @description Get a list of Conference Members
-   * @param options
+   * Gets a list of conference members or a specific member
+   *
+   * @param options - Configuration options for the conference members request
+   *
+   * Required options:
+   * - `hitlSessionId` - (string) ID of the HITL session
+   *
+   * Optional options:
+   * - `memberId` - (Optional, string) Get specific member by ID
+   * - `timeout` - (Optional, number) Request timeout in milliseconds
+   * - `version` - (Optional, string | number) API version to use
+   *
+   * @returns {Promise<GetConferenceMembersResponse | ConferenceMember>} Promise resolving to:
+   * - Either a list of conference members or a single member if memberId is provided
+   *
+   * @example
+   * ```typescript
+   * // Get all members in a conference
+   * const response = await hitlApi.conferences.getConferenceMembers({
+   *   hitlSessionId: 'session123'
+   * });
+   *
+   * // Get a specific member
+   * const member = await hitlApi.conferences.getConferenceMembers({
+   *   hitlSessionId: 'session123',
+   *   memberId: 'member456'
+   * });
+   * ```
+   *
+   * @remarks
+   * Makes a GET request to the `/conferences` endpoint
+   * @public
    */
   public static getConferenceMembers(
-    { hitlSessionId, memberId, ...options }: GetConferenceMembersOptions
-  ): Promise<GetConferenceMembersResponse | Conference> {
+    { hitlSessionId, memberId, ...options }: GetConferenceMembersOptions,
+  ): Promise<GetConferenceMembersResponse | ConferenceMember> {
     const route = this.getBaseUrl(options);
 
     return this.request({
@@ -31,8 +94,39 @@ export class Conferences extends HITLBase {
   }
 
   /**
-   * @description Upsert Conference Member
-   * @param options
+   * Adds or updates a conference member
+   *
+   * @param options - Configuration options for adding/updating the conference member
+   *
+   * Required options:
+   * - `hitlSessionId` - (string) ID of the HITL session
+   * - `identifier` - (string) Unique identifier for the member
+   * - `type` - (string) Type of the conference member
+   *
+   * Optional options:
+   * - `memberId` - (Optional, string) ID of the member to update
+   * - `status` - (Optional, string) Member's status
+   * - `state` - (Optional, string) Member's state
+   * - `disconnectedAt` - (Optional, Date) Timestamp when member disconnected
+   * - `timeout` - (Optional, number) Request timeout in milliseconds
+   * - `version` - (Optional, string | number) API version to use
+   *
+   * @returns {Promise<ConferenceMember>} Promise resolving to the created/updated conference member
+   *
+   * @example
+   * ```typescript
+   * const member = await hitlApi.conferences.addOrUpdateConferenceMember({
+   *   hitlSessionId: 'session123',
+   *   identifier: 'user456',
+   *   type: 'participant',
+   *   status: 'active',
+   *   state: 'connected'
+   * });
+   * ```
+   *
+   * @remarks
+   * Makes a POST request to the `/conferences` endpoint
+   * @public
    */
   public static addOrUpdateConferenceMember(
     {
@@ -44,8 +138,8 @@ export class Conferences extends HITLBase {
       state,
       disconnectedAt,
       ...options
-    }: AddOrUpdateConferenceMemberOptions
-  ): Promise<Conference> {
+    }: AddOrUpdateConferenceMemberOptions,
+  ): Promise<ConferenceMember> {
     const route = this.getBaseUrl(options);
 
     return this.request({
@@ -65,11 +159,40 @@ export class Conferences extends HITLBase {
   }
 
   /**
-   * @description Delete Conference Members
-   * @param options
+   * Removes conference members from a session
+   *
+   * @param options - Configuration options for cleaning up the conference
+   *
+   * Required options:
+   * - `hitlSessionId` - (string) ID of the HITL session to clean up
+   *
+   * Optional options:
+   * - `memberId` - (Optional, string) Specific member to remove
+   * - `timeout` - (Optional, number) Request timeout in milliseconds
+   * - `version` - (Optional, string | number) API version to use
+   *
+   * @returns {Promise<void>} Promise that resolves when cleanup is complete
+   *
+   * @example
+   * ```typescript
+   * // Clean up entire conference
+   * await hitlApi.conferences.cleanUpConference({
+   *   hitlSessionId: 'session123'
+   * });
+   *
+   * // Remove specific member
+   * await hitlApi.conferences.cleanUpConference({
+   *   hitlSessionId: 'session123',
+   *   memberId: 'member456'
+   * });
+   * ```
+   *
+   * @remarks
+   * Makes a DELETE request to the `/conferences` endpoint
+   * @public
    */
   public static cleanUpConference(
-    { hitlSessionId, memberId, ...options }: CleanUpConferenceOptions
+    { hitlSessionId, memberId, ...options }: CleanUpConferenceOptions,
   ): Promise<void> {
     const route = this.getBaseUrl(options);
 

package/src/api/ContactRuleGroups.ts

@@ -18,11 +18,11 @@ export class ContactRuleGroups extends HITLBase {
    * @param options
    */
   public static searchContactRuleGroups(
-    { groupIdList, ...options }: SearchRuleGroupsOptions = {}
+    { groupIdList, ...options }: SearchRuleGroupsOptions = {},
   ): Promise<SearchRuleGroupsResponse | RuleGroup> {
     const route = this.getBaseUrl(options);
     const params = Object.fromEntries(
-      Object.entries(options).filter(([key]) => ![...DEFAULT_OMIT_FIELDS, 'accountId'].includes(key))
+      Object.entries(options).filter(([key]) => ![...DEFAULT_OMIT_FIELDS, 'accountId'].includes(key)),
     );
 
     return this.request({
@@ -38,7 +38,7 @@ export class ContactRuleGroups extends HITLBase {
    * @param options
    */
   public static createContactRuleGroup(
-    { groupId, name, rules, ...options }: CreateRuleGroupOptions
+    { groupId, name, rules, ...options }: CreateRuleGroupOptions,
   ): Promise<RuleGroup> {
     const route = this.getBaseUrl(options);
 
@@ -59,7 +59,7 @@ export class ContactRuleGroups extends HITLBase {
    * @param options
    */
   public static updateContactRuleGroup(
-    { groupId, name, rules, ...options }: UpdateRuleGroupOptions
+    { groupId, name, rules, ...options }: UpdateRuleGroupOptions,
   ): Promise<RuleGroup> {
     const route = this.getBaseUrl(options);
 
@@ -80,7 +80,7 @@ export class ContactRuleGroups extends HITLBase {
    * @param options
    */
   public static deleteContactRuleGroup(
-    { groupId, ...options }: DeleteRuleGroupOptions
+    { groupId, ...options }: DeleteRuleGroupOptions,
   ): Promise<void> {
     const route = this.getBaseUrl(options);
 

package/src/api/Contacts.ts

@@ -11,7 +11,7 @@ export class Contacts extends HITLBase {
    * @param options
    */
   public static async searchContacts(
-    options: SearchContactsOptions
+    options: SearchContactsOptions,
   ): Promise<SearchContactsResponse> {
     const route = this.getBaseUrl(options);