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

package/lib/qp-bridge.d.ts

@@ -1,11 +1,76 @@
-import { Group, Question, QuestionOptional } from './qp-bridge-types';
+import { Entity, Group, GroupOptional, MediaItem, Question, QuestionOptional } from './qp-bridge-types';
+/**
+ * Creates a MediaItem from the provided parameters and content.
+ *
+ * @param name - Name of the media item.
+ * @param mimeType - MIME type of the media item.
+ * @param content - Content as File, Blob, base64 string, or ArrayBuffer.
+ * @param id - Optional id for the media item. If not provided, a UUID will be generated.
+ * @returns MediaItem object with blobUrl generated from the content.
+ */
+export declare function createMediaItem(name: string, mimeType: string, content: File): MediaItem;
+/**
+ * @param name - Name of the media item.
+ * @param mimeType - MIME type of the media item.
+ * @param content - Content as Blob.
+ */
+export declare function createMediaItem(name: string, mimeType: string, content: Blob): MediaItem;
+/**
+ * @param name - Name of the media item.
+ * @param mimeType - MIME type of the media item.
+ * @param content - Content as base64 string or binary string.
+ */
+export declare function createMediaItem(name: string, mimeType: string, content: string): MediaItem;
+/**
+ * @param name - Name of the media item.
+ * @param mimeType - MIME type of the media item.
+ * @param content - Content as ArrayBuffer.
+ */
+export declare function createMediaItem(name: string, mimeType: string, content: ArrayBuffer): MediaItem;
+export declare function createMediaItem(name: string, mimeType: string, content: File | Blob | string | ArrayBuffer, id?: string): MediaItem;
+/**
+ * Updates a MediaItem with the provided changes.
+ *
+ * @param mediaItem - The original MediaItem to update.
+ * @param updates - Object containing properties to update (name, mimeType, content).
+ * @returns Updated MediaItem object.
+ */
+export declare function updateMediaItem(mediaItem: MediaItem, updates: {
+    content: File;
+}): MediaItem;
+/**
+ * @param mediaItem - The original MediaItem to update.
+ * @param updates - Object containing content as Blob.
+ */
+export declare function updateMediaItem(mediaItem: MediaItem, updates: {
+    content: Blob;
+}): MediaItem;
+/**
+ * @param mediaItem - The original MediaItem to update.
+ * @param updates - Object containing content as base64 string or binary string.
+ */
+export declare function updateMediaItem(mediaItem: MediaItem, updates: {
+    content: string;
+}): MediaItem;
+/**
+ * @param mediaItem - The original MediaItem to update.
+ * @param updates - Object containing content as ArrayBuffer.
+ */
+export declare function updateMediaItem(mediaItem: MediaItem, updates: {
+    content: ArrayBuffer;
+}): MediaItem;
+export declare function updateMediaItem(mediaItem: MediaItem, updates: Partial<{
+    name: string;
+    mimeType: string;
+    content: File | Blob | string | ArrayBuffer;
+}>): MediaItem;
 /**
  * Sets the answer for a specific question in the questionnaire.
  *
  * @param {string} questionName - Name of the question for which the answer is being set.
  * @param {*} answer - The answer to set for the question. Can be any type.
  * @returns {Promise<void>} A promise that resolves when the answer has been successfully set.
- * @throws {Error} Throws if the message from the parent window indicates a failure.
+ * @throws {Error} Throws if the operation fails.
  * @example
  * ```typescript
  * await setAnswer('favoriteColor', 'blue');
@@ -18,7 +83,7 @@ export declare function setAnswer(questionName: string, answer: unknown): Promis
  *
  * @param {string} name - The name of the question to retrieve.
  * @returns {Promise<Question>} A promise that resolves to the question object.
- * @throws {Error} Throws if the message from the parent window indicates a failure.
+ * @throws {Error} Throws if the question is not found or the operation fails.
  * @example
  * ```typescript
  * const question = await getQuestion('favoriteColor');
@@ -32,7 +97,7 @@ export declare function getQuestion(name: string): Promise<Question>;
  * @param {string} name - The name of the question to update. This is a unique identifier and cannot be changed.
  * @param {QuestionOptional} questionData - The updated question data excluding the name property.
  * @returns {Promise<void>} A promise that resolves when the question has been successfully updated.
- * @throws {Error} Throws if the message from the parent window indicates a failure.
+ * @throws {Error} Throws if the question is not found or the operation fails.
  * @example
  * ```typescript
  * await setQuestion('favoriteColor', { label: 'What is your favorite color?' });
@@ -44,7 +109,7 @@ export declare function setQuestion(name: string, questionData: QuestionOptional
  *
  * @param {string} name - The name of the group to retrieve.
  * @returns {Promise<Group>} A promise that resolves to the group object.
- * @throws {Error} Throws if the message from the parent window indicates a failure.
+ * @throws {Error} Throws if the group is not found or the operation fails.
  * @example
  * ```typescript
  * const group = await getGroup('personalInfo');
@@ -54,16 +119,28 @@ export declare function setQuestion(name: string, questionData: QuestionOptional
  * ```
  */
 export declare function getGroup(name: string): Promise<Group>;
+/**
+ * Updates a group in the questionnaire.
+ *
+ * @param {string} name - The name of the group to update. This is a unique identifier and cannot be changed.
+ * @param {GroupOptional} groupData - The updated group data excluding the name property.
+ * @returns {Promise<void>} A promise that resolves when the group has been successfully updated.
+ * @throws {Error} Throws if the group is not found or the operation fails.
+ * @example
+ * ```typescript
+ * await setGroup('personalInfo', { label: 'Personal Information', hidden: false, collapsed: true });
+ * ```
+ */
+export declare function setGroup(name: string, groupData: GroupOptional): Promise<void>;
 /**
  * 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.
  * @param listener - A function that will be called with the question name and the new answer whenever an answer changes.
  * @return An object with a `cancelSubscription` method to stop listening for changes.
  * @example
  * ```typescript
  * import { onAnswerChange } from 'qp-bridge';
- * const { cancelSubsctiprion } = onAnswerChange((question, answer) => {
+ * const { cancelSubscription } = onAnswerChange((question, answer) => {
  *  console.log(`Answer for ${question} changed to:`, answer);
  *  });
  *
@@ -74,3 +151,162 @@ export declare function getGroup(name: string): Promise<Group>;
 export declare function onAnswerChange(listener: (question: string, answer: unknown) => void): {
     cancelSubscription: () => void;
 };
+/**
+ * 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.
+ *
+ * @typeParam T - The resolved type of the provided async action.
+ * @param action - A function returning a promise whose execution should be wrapped.
+ * @returns A promise resolving to the value returned by the action.
+ * @throws Propagates any error thrown/rejected by the provided action.
+ * @example
+ * ```typescript
+ * const result = await withBusyIndicator(async () => {
+ *   await setAnswer('favoriteColor', 'blue');
+ *   return 'done';
+ * });
+ * console.log(result); // 'done'
+ * ```
+ */
+export declare function withBusyIndicator<T>(action: () => Promise<T>): Promise<T>;
+/**
+ * Saves the current questionnaire state.
+ * Triggers a save operation for the questionnaire data.
+ *
+ * @returns {Promise<void>} A promise that resolves when the questionnaire has been successfully saved.
+ * @throws {Error} Throws if the save operation fails.
+ * @example
+ * ```typescript
+ * await saveQuestionnaire();
+ * console.log('Questionnaire saved successfully');
+ * ```
+ */
+export declare function saveQuestionnaire(): Promise<void>;
+/**
+ * Completes and closes the current questionnaire.
+ * Triggers the complete and close operation for the questionnaire.
+ *
+ * @returns {Promise<void>} A promise that resolves when the questionnaire has been successfully completed and closed.
+ * @throws {Error} Throws if the complete and close operation fails.
+ * @example
+ * ```typescript
+ * await completeAndCloseQuestionnaire();
+ * console.log('Questionnaire completed and closed successfully');
+ * ```
+ */
+export declare function completeAndCloseQuestionnaire(): Promise<void>;
+/**
+ * Executes a custom command by its name.
+ * Triggers the execution of any user-defined command in the questionnaire.
+ *
+ * @param {string} commandName - The name of the command to execute.
+ * @returns {Promise<void>} A promise that resolves when the command has been successfully executed.
+ * @throws {Error} Throws if the command is not found or the execution fails.
+ * @example
+ * ```typescript
+ * await executeCustomCommand('MyCustomCommand');
+ * console.log('Custom command executed successfully');
+ * ```
+ */
+export declare function executeCustomCommand(commandName: string): Promise<void>;
+type Validator = () => Promise<boolean>;
+/**
+ * Registers a validator function to be called when a save event occurs.
+ * Useful for validating data before saving the questionnaire.
+ *
+ * @param 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.
+ * @example
+ * ```typescript
+ * import { onSave } from 'qp-bridge';
+ * const { cancelSubscription } = onSave(async () => {
+ *   // perform validation logic
+ *   return true;
+ * });
+ *
+ * // To stop listening for save events:
+ * cancelSubscription();
+ * ```
+ */
+export declare function onSave(validator: Validator): {
+    cancelSubscription: () => void;
+};
+/**
+ * Fetches entities from the CRM system using the provided FetchXML query.
+ *
+ * @param {string} fetchXml - The FetchXML query string to execute.
+ * @returns {Promise<Entity[]>} A promise that resolves to an array of entities.
+ * @throws {Error} Throws if the fetch operation fails or if no entities are found.
+ * @example
+ * ```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
+ * ```
+ */
+export declare function fetchEntities(fetchXml: string): Promise<Entity[]>;
+/**
+ * Retrieves a single entity by its name and ID from the CRM system.
+ *
+ * @param {string} entityName - The name of the entity to retrieve (e.g., "contact", "account").
+ * @param {string} id - The unique identifier of the entity.
+ * @returns {Promise<Entity>} A promise that resolves to the entity object.
+ * @throws {Error} Throws if the entity is not found or the operation fails.
+ * @example
+ * ```typescript
+ * const contact = await getEntityById('contact', '12345678-1234-1234-1234-123456789abc');
+ * console.log(contact.attributes.firstname); // Entity firstname attribute
+ * ```
+ */
+export declare function getEntityById(entityName: string, id: string): Promise<Entity>;
+/**
+ * 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.
+ *
+ * @param {string} repeatableGroupName - The name of the parent repeatable group.
+ * @param {number} groupIndex - The index (0-based) of the group instance to repeat.
+ * @returns {Promise<void>} A promise that resolves when the group has been successfully repeated.
+ * @throws {Error} Throws if the parent group is not found, is not a repeatable group, the index is invalid, or the operation fails.
+ * @example
+ * ```typescript
+ * await repeatGroup('personalInfoRepeatable', 1);
+ * console.log('Group repeated successfully');
+ * ```
+ */
+export declare function repeatGroup(repeatableGroupName: string, groupIndex: number): Promise<void>;
+/**
+ * Adds a new group instance to a repeatable group.
+ * The specified name must refer to a repeatable group.
+ *
+ * @param {string} repeatableGroupName - The name of the repeatable group to add a new instance to.
+ * @returns {Promise<void>} A promise that resolves when the new group has been successfully added.
+ * @throws {Error} Throws if the repeatable group is not found or the operation fails.
+ * @example
+ * ```typescript
+ * await addNewGroup('personalInfoRepeatable');
+ * console.log('New group added successfully');
+ * ```
+ */
+export declare function addNewGroup(repeatableGroupName: string): Promise<void>;
+/**
+ * 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.
+ *
+ * @param {string} repeatableGroupName - The name of the parent repeatable group.
+ * @param {number} groupIndex - The index (0-based) of the group instance to delete.
+ * @returns {Promise<void>} A promise that resolves when the group has been successfully deleted.
+ * @throws {Error} Throws if the parent group is not found, is not a repeatable group, the index is invalid, or the operation fails.
+ * @example
+ * ```typescript
+ * await deleteGroup('personalInfoRepeatable', 1);
+ * console.log('Group deleted successfully');
+ * ```
+ */
+export declare function deleteGroup(repeatableGroupName: string, groupIndex: number): Promise<void>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@resconet/qp-bridge",
-	"version": "0.0.1-alpha.9",
+	"version": "1.0.0-alpha.26",
 	"dependencies": {
 		"zod": "^3.23.8",
 		"uuid": "^9.0.1"