@resconet/qp-bridge 0.0.1-alpha.9 → 1.0.0

package/README.md

@@ -7,7 +7,7 @@ A JavaScript bridge library for communication between iframes in Questionnaire a
 
 ## Description
 
-qp-bridge provides a simple and reliable way to communicate between components in questionnaire environments. It handles messaging, serialization, and error handling for seamless interaction.
+qp-bridge provides a simple and reliable way to communicate between questionnaire and users logic.
 
 ## Installation
 
@@ -41,11 +41,352 @@ await setAnswer("numericQuestion", 42);
 
 ## Functions
 
+- [createMediaItem](#createmediaitem)
+- [createMediaItem](#createmediaitem)
+- [createMediaItem](#createmediaitem)
+- [createMediaItem](#createmediaitem)
+- [createMediaItem](#createmediaitem)
+- [createMediaItem](#createmediaitem)
+- [updateMediaItem](#updatemediaitem)
+- [updateMediaItem](#updatemediaitem)
+- [updateMediaItem](#updatemediaitem)
+- [updateMediaItem](#updatemediaitem)
+- [updateMediaItem](#updatemediaitem)
+- [updateMediaItem](#updatemediaitem)
 - [setAnswer](#setanswer)
 - [getQuestion](#getquestion)
 - [setQuestion](#setquestion)
 - [getGroup](#getgroup)
+- [setGroup](#setgroup)
 - [onAnswerChange](#onanswerchange)
+- [withBusyIndicator](#withbusyindicator)
+- [saveQuestionnaire](#savequestionnaire)
+- [completeAndCloseQuestionnaire](#completeandclosequestionnaire)
+- [executeCustomCommand](#executecustomcommand)
+- [onSave](#onsave)
+- [fetchEntities](#fetchentities)
+- [getEntityById](#getentitybyid)
+- [repeatGroup](#repeatgroup)
+- [addNewGroup](#addnewgroup)
+- [deleteGroup](#deletegroup)
+
+### createMediaItem
+
+Creates a MediaItem from the provided parameters and content.
+
+| Function | Type |
+| ---------- | ---------- |
+| `createMediaItem` | `{ (name: string, mimeType: string, content: File): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: Blob): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: string): { ...; }; (name: string, mimeType:...` |
+
+Parameters:
+
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as File, Blob, base64 string, or ArrayBuffer.
+* `id`: - Optional id for the media item. If not provided, a UUID will be generated.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as Blob.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as base64 string or binary string.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as ArrayBuffer.
+
+
+Returns:
+
+MediaItem object with blobUrl generated from the content.
+
+### createMediaItem
+
+Creates a MediaItem from the provided parameters and content.
+
+| Function | Type |
+| ---------- | ---------- |
+| `createMediaItem` | `{ (name: string, mimeType: string, content: File): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: Blob): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: string): { ...; }; (name: string, mimeType:...` |
+
+Parameters:
+
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as File, Blob, base64 string, or ArrayBuffer.
+* `id`: - Optional id for the media item. If not provided, a UUID will be generated.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as Blob.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as base64 string or binary string.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as ArrayBuffer.
+
+
+Returns:
+
+MediaItem object with blobUrl generated from the content.
+
+### createMediaItem
+
+Creates a MediaItem from the provided parameters and content.
+
+| Function | Type |
+| ---------- | ---------- |
+| `createMediaItem` | `{ (name: string, mimeType: string, content: File): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: Blob): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: string): { ...; }; (name: string, mimeType:...` |
+
+Parameters:
+
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as File, Blob, base64 string, or ArrayBuffer.
+* `id`: - Optional id for the media item. If not provided, a UUID will be generated.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as Blob.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as base64 string or binary string.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as ArrayBuffer.
+
+
+Returns:
+
+MediaItem object with blobUrl generated from the content.
+
+### createMediaItem
+
+Creates a MediaItem from the provided parameters and content.
+
+| Function | Type |
+| ---------- | ---------- |
+| `createMediaItem` | `{ (name: string, mimeType: string, content: File): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: Blob): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: string): { ...; }; (name: string, mimeType:...` |
+
+Parameters:
+
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as File, Blob, base64 string, or ArrayBuffer.
+* `id`: - Optional id for the media item. If not provided, a UUID will be generated.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as Blob.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as base64 string or binary string.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as ArrayBuffer.
+
+
+Returns:
+
+MediaItem object with blobUrl generated from the content.
+
+### createMediaItem
+
+Creates a MediaItem from the provided parameters and content.
+
+| Function | Type |
+| ---------- | ---------- |
+| `createMediaItem` | `{ (name: string, mimeType: string, content: File): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: Blob): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: string): { ...; }; (name: string, mimeType:...` |
+
+Parameters:
+
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as File, Blob, base64 string, or ArrayBuffer.
+* `id`: - Optional id for the media item. If not provided, a UUID will be generated.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as Blob.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as base64 string or binary string.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as ArrayBuffer.
+
+
+Returns:
+
+MediaItem object with blobUrl generated from the content.
+
+### createMediaItem
+
+Creates a MediaItem from the provided parameters and content.
+
+| Function | Type |
+| ---------- | ---------- |
+| `createMediaItem` | `{ (name: string, mimeType: string, content: File): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: Blob): { id: string; name: string; mimeType: string; blobUrl: string; }; (name: string, mimeType: string, content: string): { ...; }; (name: string, mimeType:...` |
+
+Parameters:
+
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as File, Blob, base64 string, or ArrayBuffer.
+* `id`: - Optional id for the media item. If not provided, a UUID will be generated.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as Blob.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as base64 string or binary string.
+* `name`: - Name of the media item.
+* `mimeType`: - MIME type of the media item.
+* `content`: - Content as ArrayBuffer.
+
+
+Returns:
+
+MediaItem object with blobUrl generated from the content.
+
+### updateMediaItem
+
+Updates a MediaItem with the provided changes.
+
+| Function | Type |
+| ---------- | ---------- |
+| `updateMediaItem` | `{ (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { content: File; }): { id: string; name: string; mimeType: string; blobUrl: string; }; (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { ...; }): { ...; }; (mediaItem: { ...; }, updates: { ...` |
+
+Parameters:
+
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing properties to update (name, mimeType, content).
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as Blob.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as base64 string or binary string.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as ArrayBuffer.
+
+
+Returns:
+
+Updated MediaItem object.
+
+### updateMediaItem
+
+Updates a MediaItem with the provided changes.
+
+| Function | Type |
+| ---------- | ---------- |
+| `updateMediaItem` | `{ (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { content: File; }): { id: string; name: string; mimeType: string; blobUrl: string; }; (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { ...; }): { ...; }; (mediaItem: { ...; }, updates: { ...` |
+
+Parameters:
+
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing properties to update (name, mimeType, content).
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as Blob.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as base64 string or binary string.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as ArrayBuffer.
+
+
+Returns:
+
+Updated MediaItem object.
+
+### updateMediaItem
+
+Updates a MediaItem with the provided changes.
+
+| Function | Type |
+| ---------- | ---------- |
+| `updateMediaItem` | `{ (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { content: File; }): { id: string; name: string; mimeType: string; blobUrl: string; }; (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { ...; }): { ...; }; (mediaItem: { ...; }, updates: { ...` |
+
+Parameters:
+
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing properties to update (name, mimeType, content).
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as Blob.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as base64 string or binary string.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as ArrayBuffer.
+
+
+Returns:
+
+Updated MediaItem object.
+
+### updateMediaItem
+
+Updates a MediaItem with the provided changes.
+
+| Function | Type |
+| ---------- | ---------- |
+| `updateMediaItem` | `{ (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { content: File; }): { id: string; name: string; mimeType: string; blobUrl: string; }; (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { ...; }): { ...; }; (mediaItem: { ...; }, updates: { ...` |
+
+Parameters:
+
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing properties to update (name, mimeType, content).
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as Blob.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as base64 string or binary string.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as ArrayBuffer.
+
+
+Returns:
+
+Updated MediaItem object.
+
+### updateMediaItem
+
+Updates a MediaItem with the provided changes.
+
+| Function | Type |
+| ---------- | ---------- |
+| `updateMediaItem` | `{ (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { content: File; }): { id: string; name: string; mimeType: string; blobUrl: string; }; (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { ...; }): { ...; }; (mediaItem: { ...; }, updates: { ...` |
+
+Parameters:
+
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing properties to update (name, mimeType, content).
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as Blob.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as base64 string or binary string.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as ArrayBuffer.
+
+
+Returns:
+
+Updated MediaItem object.
+
+### updateMediaItem
+
+Updates a MediaItem with the provided changes.
+
+| Function | Type |
+| ---------- | ---------- |
+| `updateMediaItem` | `{ (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { content: File; }): { id: string; name: string; mimeType: string; blobUrl: string; }; (mediaItem: { id: string; name: string; mimeType: string; blobUrl: string; }, updates: { ...; }): { ...; }; (mediaItem: { ...; }, updates: { ...` |
+
+Parameters:
+
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing properties to update (name, mimeType, content).
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as Blob.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as base64 string or binary string.
+* `mediaItem`: - The original MediaItem to update.
+* `updates`: - Object containing content as ArrayBuffer.
+
+
+Returns:
+
+Updated MediaItem object.
 
 ### setAnswer
 
@@ -78,7 +419,7 @@ Retrieves a question by its name from the questionnaire.
 
 | Function | Type |
 | ---------- | ---------- |
-| `getQuestion` | `(name: string) => Promise<{ label: string; description: string; disabled: boolean; required: boolean; hidden: boolean; semanticColor?: string or undefined; }>` |
+| `getQuestion` | `(name: string) => Promise<{ label: string; description: string; disabled: boolean; required: boolean; hidden: boolean; semanticColor?: string or undefined; errorMessage?: string or undefined; answer?: unknown; }>` |
 
 Parameters:
 
@@ -103,7 +444,7 @@ Updates a question in the questionnaire.
 
 | Function | Type |
 | ---------- | ---------- |
-| `setQuestion` | `(name: string, questionData: { semanticColor?: string or undefined; label?: string or undefined; description?: string or undefined; disabled?: boolean or undefined; required?: boolean or undefined; hidden?: boolean or undefined; }) => Promise<...>` |
+| `setQuestion` | `(name: string, questionData: { semanticColor?: string or undefined; label?: string or undefined; description?: string or undefined; disabled?: boolean or undefined; required?: boolean or undefined; hidden?: boolean or undefined; errorMessage?: string or undefined; answer?: unknown; }) => Promise<...>` |
 
 Parameters:
 
@@ -149,11 +490,35 @@ console.log(group.collapsed); // Outputs whether the group is collapsed
 ```
 
 
+### setGroup
+
+Updates a group in the questionnaire.
+
+| Function | Type |
+| ---------- | ---------- |
+| `setGroup` | `(name: string, groupData: { label?: string or undefined; hidden?: boolean or undefined; collapsed?: boolean or undefined; }) => Promise<void>` |
+
+Parameters:
+
+* `name`: - The name of the group to update. This is a unique identifier and cannot be changed.
+* `groupData`: - The updated group data excluding the name property.
+
+
+Returns:
+
+A promise that resolves when the group has been successfully updated.
+
+Examples:
+
+```typescript
+await setGroup('personalInfo', { label: 'Personal Information', hidden: false, collapsed: true });
+```
+
+
 ### onAnswerChange
 
 Subscribes to changes in answers for questions.
-This function listens for messages from the parent window
-and invokes the provided listener whenever an answer changes.
+Calls the provided listener whenever an answer changes in the questionnaire.
 
 | Function | Type |
 | ---------- | ---------- |
@@ -168,7 +533,7 @@ Examples:
 
 ```typescript
 import { onAnswerChange } from 'qp-bridge';
-const { cancelSubsctiprion } = onAnswerChange((question, answer) => {
+const { cancelSubscription } = onAnswerChange((question, answer) => {
  console.log(`Answer for ${question} changed to:`, answer);
  });
 
@@ -177,6 +542,273 @@ cancelSubscription();
 ```
 
 
+### withBusyIndicator
+
+Wraps an asynchronous action with a busy indicator in the host application.
+Shows a loading indicator during the execution of the provided action,
+ensuring the UI reflects the busy state appropriately.
+
+| Function | Type |
+| ---------- | ---------- |
+| `withBusyIndicator` | `<T>(action: () => Promise<T>) => Promise<T>` |
+
+Parameters:
+
+* `action`: - A function returning a promise whose execution should be wrapped.
+
+
+Returns:
+
+A promise resolving to the value returned by the action.
+
+Examples:
+
+```typescript
+const result = await withBusyIndicator(async () => {
+  await setAnswer('favoriteColor', 'blue');
+  return 'done';
+});
+console.log(result); // 'done'
+```
+
+
+### saveQuestionnaire
+
+Saves the current questionnaire state.
+Triggers a save operation for the questionnaire data.
+
+| Function | Type |
+| ---------- | ---------- |
+| `saveQuestionnaire` | `() => Promise<void>` |
+
+Returns:
+
+A promise that resolves when the questionnaire has been successfully saved.
+
+Examples:
+
+```typescript
+await saveQuestionnaire();
+console.log('Questionnaire saved successfully');
+```
+
+
+### completeAndCloseQuestionnaire
+
+Completes and closes the current questionnaire.
+Triggers the complete and close operation for the questionnaire.
+
+| Function | Type |
+| ---------- | ---------- |
+| `completeAndCloseQuestionnaire` | `() => Promise<void>` |
+
+Returns:
+
+A promise that resolves when the questionnaire has been successfully completed and closed.
+
+Examples:
+
+```typescript
+await completeAndCloseQuestionnaire();
+console.log('Questionnaire completed and closed successfully');
+```
+
+
+### executeCustomCommand
+
+Executes a custom command by its name.
+Triggers the execution of any user-defined command in the questionnaire.
+
+| Function | Type |
+| ---------- | ---------- |
+| `executeCustomCommand` | `(commandName: string) => Promise<void>` |
+
+Parameters:
+
+* `commandName`: - The name of the command to execute.
+
+
+Returns:
+
+A promise that resolves when the command has been successfully executed.
+
+Examples:
+
+```typescript
+await executeCustomCommand('MyCustomCommand');
+console.log('Custom command executed successfully');
+```
+
+
+### onSave
+
+Registers a validator function to be called when a save event occurs.
+Useful for validating data before saving the questionnaire.
+
+| Function | Type |
+| ---------- | ---------- |
+| `onSave` | `(validator: Validator) => { cancelSubscription: () => void; }` |
+
+Parameters:
+
+* `validator`: - A function returning a Promise resolving to a boolean indicating if the save is valid.
+
+
+Returns:
+
+An object with a `cancelSubscription` method to unregister the validator.
+
+Examples:
+
+```typescript
+import { onSave } from 'qp-bridge';
+const { cancelSubscription } = onSave(async () => {
+  // perform validation logic
+  return true;
+});
+
+// To stop listening for save events:
+cancelSubscription();
+```
+
+
+### fetchEntities
+
+Fetches entities from the CRM system using the provided FetchXML query.
+
+| Function | Type |
+| ---------- | ---------- |
+| `fetchEntities` | `(fetchXml: string) => Promise<Record<string, unknown>[]>` |
+
+Parameters:
+
+* `fetchXml`: - The FetchXML query string to execute.
+
+
+Returns:
+
+A promise that resolves to an array of entities.
+
+Examples:
+
+```typescript
+const fetchXml = `<fetch top="10">
+  <entity name="contact">
+    <attribute name="firstname" />
+    <attribute name="lastname" />
+  </entity>
+</fetch>`;
+const entities = await fetchEntities(fetchXml);
+console.log(entities); // Array of contact entities
+```
+
+
+### getEntityById
+
+Retrieves a single entity by its name and ID from the CRM system.
+
+| Function | Type |
+| ---------- | ---------- |
+| `getEntityById` | `(entityName: string, id: string) => Promise<Record<string, unknown>>` |
+
+Parameters:
+
+* `entityName`: - The name of the entity to retrieve (e.g., "contact", "account").
+* `id`: - The unique identifier of the entity.
+
+
+Returns:
+
+A promise that resolves to the entity object.
+
+Examples:
+
+```typescript
+const contact = await getEntityById('contact', '12345678-1234-1234-1234-123456789abc');
+console.log(contact.attributes.firstname); // Entity firstname attribute
+```
+
+
+### repeatGroup
+
+Repeats a specific group within a repeatable group by creating a copy of the group at the specified index.
+The parent group must be a repeatable group and the index must refer to an existing group instance.
+
+| Function | Type |
+| ---------- | ---------- |
+| `repeatGroup` | `(repeatableGroupName: string, groupIndex: number) => Promise<void>` |
+
+Parameters:
+
+* `repeatableGroupName`: - The name of the parent repeatable group.
+* `groupIndex`: - The index (0-based) of the group instance to repeat.
+
+
+Returns:
+
+A promise that resolves when the group has been successfully repeated.
+
+Examples:
+
+```typescript
+await repeatGroup('personalInfoRepeatable', 1);
+console.log('Group repeated successfully');
+```
+
+
+### addNewGroup
+
+Adds a new group instance to a repeatable group.
+The specified name must refer to a repeatable group.
+
+| Function | Type |
+| ---------- | ---------- |
+| `addNewGroup` | `(repeatableGroupName: string) => Promise<void>` |
+
+Parameters:
+
+* `repeatableGroupName`: - The name of the repeatable group to add a new instance to.
+
+
+Returns:
+
+A promise that resolves when the new group has been successfully added.
+
+Examples:
+
+```typescript
+await addNewGroup('personalInfoRepeatable');
+console.log('New group added successfully');
+```
+
+
+### deleteGroup
+
+Deletes a specific group instance from a repeatable group by index.
+The parent group must be a repeatable group and the index must refer to an existing group instance.
+
+| Function | Type |
+| ---------- | ---------- |
+| `deleteGroup` | `(repeatableGroupName: string, groupIndex: number) => Promise<void>` |
+
+Parameters:
+
+* `repeatableGroupName`: - The name of the parent repeatable group.
+* `groupIndex`: - The index (0-based) of the group instance to delete.
+
+
+Returns:
+
+A promise that resolves when the group has been successfully deleted.
+
+Examples:
+
+```typescript
+await deleteGroup('personalInfoRepeatable', 1);
+console.log('Group deleted successfully');
+```
+
+
 
 
 <!-- TSDOC_END -->