@icure/api 8.6.5 → 8.6.7

package/icc-x-api/icc-contact-x-api.js

@@ -125,7 +125,7 @@ class IccContactXApi extends icc_api_1.IccContactApi {
         });
     }
     /**
-     * Same as {@link findIdsBy} but it will only return the ids of the contacts. It can also filter the contacts where Contact.openingDate is between
+     * Same as {@link findBy} but it will only return the ids of the contacts. It can also filter the contacts where Contact.openingDate is between
      * startDate and endDate in ascending or descending order by that field. (default: ascending).
      */
     findIdsBy(hcpartyId, patient, startDate, endDate, descending) {
@@ -220,43 +220,106 @@ class IccContactXApi extends icc_api_1.IccContactApi {
             .findByHCPartyPatientSecretFKeysUsingPost(hcPartyId, planOfActionIds, skipClosedContacts, secretFKeys)
             .then((contacts) => this.decrypt(hcPartyId, contacts));
     }
+    /**
+     * Filters contacts using a filter chain and decrypts the results for the given user.
+     * @param user the user for decryption
+     * @param startDocumentId optional document id to start pagination from
+     * @param limit maximum number of results to return
+     * @param body the filter chain to apply
+     * @return a paginated list of decrypted contacts
+     */
     filterByWithUser(user, startDocumentId, limit, body) {
         return super
             .filterContactsBy(startDocumentId, limit, body)
             .then((ctcs) => this.decrypt(user.healthcarePartyId || user.patientId, ctcs.rows).then((decryptedRows) => Object.assign(ctcs, { rows: decryptedRows })));
     }
+    /**
+     * Lists contacts by opening date within a date range and decrypts the results for the given user.
+     * @param user the user for decryption
+     * @param startDate start of the date range (format: YYYYMMDDHHmmss)
+     * @param endDate end of the date range (format: YYYYMMDDHHmmss)
+     * @param hcpartyid the healthcare party id
+     * @param startKey optional start key for pagination
+     * @param startDocumentId optional document id to start pagination from
+     * @param limit maximum number of results to return
+     * @return a paginated list of decrypted contacts
+     */
     listContactsByOpeningDateWithUser(user, startDate, endDate, hcpartyid, startKey, startDocumentId, limit) {
         return super
             .listContactsByOpeningDate(startDate, endDate, hcpartyid, startKey, startDocumentId, limit)
             .then((ctcs) => this.decrypt(user.healthcarePartyId || user.patientId, ctcs.rows).then((decryptedRows) => Object.assign(ctcs, { rows: decryptedRows })));
     }
+    /**
+     * Gets a service by id and decrypts it for the given user.
+     * @param user the user for decryption
+     * @param serviceId the service id
+     * @return the decrypted service
+     */
     getServiceWithUser(user, serviceId) {
         return super
             .getService(serviceId)
             .then((service) => { var _a, _b; return this.decryptServices((_b = (_a = user.healthcarePartyId) !== null && _a !== void 0 ? _a : user.patientId) !== null && _b !== void 0 ? _b : user.deviceId, [service]); })
             .then((decrypted) => decrypted[0]);
     }
+    /**
+     * Lists services by their ids and decrypts them for the given user.
+     * @param user the user for decryption
+     * @param serviceIds the list of service ids to retrieve
+     * @return an array of decrypted services
+     */
     listServicesWithUser(user, serviceIds) {
         var _a;
         return super
             .filterServicesBy(undefined, (_a = serviceIds.ids) === null || _a === void 0 ? void 0 : _a.length, new models_1.FilterChainService({ filter: new ServiceByIdsFilter_1.ServiceByIdsFilter({ ids: serviceIds.ids }) }))
             .then((paginatedList) => { var _a, _b, _c; return this.decryptServices((_b = (_a = user.healthcarePartyId) !== null && _a !== void 0 ? _a : user.patientId) !== null && _b !== void 0 ? _b : user.deviceId, (_c = paginatedList.rows) !== null && _c !== void 0 ? _c : []); });
     }
+    /**
+     * Finds contacts by healthcare party and form id and decrypts them for the given user.
+     * @param user the user for decryption
+     * @param hcPartyId the healthcare party id
+     * @param formId the form id
+     * @return an array of decrypted contacts
+     */
     findByHCPartyFormIdWithUser(user, hcPartyId, formId) {
         return super.findByHCPartyFormId(hcPartyId, formId).then((ctcs) => this.decrypt(this.dataOwnerApi.getDataOwnerIdOf(user), ctcs));
     }
+    /**
+     * Finds contacts by healthcare party and multiple form ids and decrypts them for the given user.
+     * @param user the user for decryption
+     * @param hcPartyId the healthcare party id
+     * @param body the list of form ids
+     * @return an array of decrypted contacts
+     */
     findByHCPartyFormIdsWithUser(user, hcPartyId, body) {
         return super.findByHCPartyFormIds(hcPartyId, body).then((ctcs) => this.decrypt(this.dataOwnerApi.getDataOwnerIdOf(user), ctcs));
     }
+    /**
+     * Gets a contact by id and decrypts it for the given user.
+     * @param user the user for decryption
+     * @param contactId the contact id
+     * @return the decrypted contact
+     */
     getContactWithUser(user, contactId) {
         return super
             .getContact(contactId)
             .then((ctc) => this.decrypt(this.dataOwnerApi.getDataOwnerIdOf(user), [ctc]))
             .then((ctcs) => ctcs[0]);
     }
+    /**
+     * Gets multiple contacts by their ids and decrypts them for the given user.
+     * @param user the user for decryption
+     * @param body the list of contact ids
+     * @return an array of decrypted contacts
+     */
     getContactsWithUser(user, body) {
         return super.getContacts(body).then((ctcs) => this.decrypt(this.dataOwnerApi.getDataOwnerIdOf(user), ctcs));
     }
+    /**
+     * Modifies an existing contact by encrypting it and saving it to the database.
+     * @param user the user for encryption
+     * @param body the contact to modify
+     * @return the modified and decrypted contact
+     */
     modifyContactWithUser(user, body) {
         return __awaiter(this, void 0, void 0, function* () {
             return body ? this.modifyContactAs(this.dataOwnerApi.getDataOwnerIdOf(user), body) : null;
@@ -268,6 +331,12 @@ class IccContactXApi extends icc_api_1.IccContactApi {
             .then((ctc) => this.decrypt(dataOwner, [ctc]))
             .then((ctcs) => ctcs[0]);
     }
+    /**
+     * Modifies multiple existing contacts by encrypting them and saving them to the database.
+     * @param user the user for encryption
+     * @param bodies the array of contacts to modify
+     * @return an array of modified and decrypted contacts
+     */
     modifyContactsWithUser(user, bodies) {
         const _super = Object.create(null, {
             modifyContacts: { get: () => super.modifyContacts }
@@ -280,6 +349,12 @@ class IccContactXApi extends icc_api_1.IccContactApi {
                 : null;
         });
     }
+    /**
+     * Creates a new contact by encrypting it and saving it to the database.
+     * @param user the user for encryption
+     * @param body the contact to create
+     * @return the created and decrypted contact
+     */
     createContactWithUser(user, body) {
         const _super = Object.create(null, {
             createContact: { get: () => super.createContact }
@@ -293,6 +368,12 @@ class IccContactXApi extends icc_api_1.IccContactApi {
                 : null;
         });
     }
+    /**
+     * Creates multiple new contacts by encrypting them and saving them to the database.
+     * @param user the user for encryption
+     * @param bodies the array of contacts to create
+     * @return an array of created and decrypted contacts
+     */
     createContactsWithUser(user, bodies) {
         const _super = Object.create(null, {
             createContacts: { get: () => super.createContacts }
@@ -305,6 +386,14 @@ class IccContactXApi extends icc_api_1.IccContactApi {
                 : null;
         });
     }
+    /**
+     * Encrypts the content and custom encrypted fields of services.
+     * Services with compound values are recursively encrypted.
+     * @param key the encryption key
+     * @param rawKey the raw encryption key as a string
+     * @param services the array of services to encrypt
+     * @return a promise containing the encrypted services
+     */
     encryptServices(key, rawKey, services) {
         return Promise.all(services.map((svc) => __awaiter(this, void 0, void 0, function* () {
             if (svc.content &&
@@ -340,6 +429,12 @@ class IccContactXApi extends icc_api_1.IccContactApi {
             }
         })));
     }
+    /**
+     * Encrypts contacts for the given user including all services within the contacts.
+     * @param user the user for encryption
+     * @param ctcs the array of contacts to encrypt
+     * @return a promise containing the encrypted contacts
+     */
     encrypt(user, ctcs) {
         return this.encryptAs(this.dataOwnerApi.getDataOwnerIdOf(user), ctcs);
     }
@@ -370,11 +465,23 @@ class IccContactXApi extends icc_api_1.IccContactApi {
             return ctcs.map((e) => allEncrypted.get(e.id));
         });
     }
+    /**
+     * Decrypts contacts and all their encrypted content.
+     * @param hcpartyId the healthcare party id (deprecated parameter, kept for compatibility)
+     * @param ctcs the array of encrypted contacts
+     * @return a promise containing the decrypted contacts
+     */
     decrypt(hcpartyId, ctcs) {
         return __awaiter(this, void 0, void 0, function* () {
             return (yield this.crypto.xapi.tryDecryptEntities(ctcs, utils_1.EntityWithDelegationTypeName.Contact, (x) => new models_1.Contact(x))).map(({ entity }) => entity);
         });
     }
+    /**
+     * Decrypts services and all their encrypted content.
+     * @param hcpartyId the healthcare party id (deprecated parameter, kept for compatibility)
+     * @param svcs the array of encrypted services
+     * @return a promise containing the decrypted services
+     */
     decryptServices(hcpartyId, svcs) {
         return __awaiter(this, void 0, void 0, function* () {
             /*TODO
@@ -386,6 +493,12 @@ class IccContactXApi extends icc_api_1.IccContactApi {
             return (yield this.crypto.xapi.tryDecryptEntities(svcs, utils_1.EntityWithDelegationTypeName.Contact, (x) => new models_1.Service(x))).map(({ entity }) => entity);
         });
     }
+    /**
+     * Finds the contact containing the given service id, prioritizing the latest version by valueDate.
+     * @param ctcs the array of contacts to search
+     * @param svcId the service id to find
+     * @return the contact containing the service or undefined if not found
+     */
     contactOfService(ctcs, svcId) {
         let latestContact = undefined;
         let latestService;
@@ -398,6 +511,12 @@ class IccContactXApi extends icc_api_1.IccContactApi {
         });
         return latestContact;
     }
+    /**
+     * Extracts and filters services from contacts, keeping only the latest version of each service and excluding deleted services.
+     * @param ctcs the array of contacts containing services
+     * @param filter a predicate function to filter services: (service, contact) => boolean
+     * @return an array of filtered services with contactId set
+     */
     filteredServices(ctcs, filter) {
         const byIds = {};
         ctcs.forEach((c) => (c.services || [])
@@ -411,16 +530,38 @@ class IccContactXApi extends icc_api_1.IccContactApi {
         }));
         return _.values(byIds).filter((s) => !s.deleted && !s.endOfLife);
     }
-    //Return a promise
+    /**
+     * Extracts and filters services from contacts, returning a promise. Same as filteredServices but wrapped in a promise.
+     * @param ctcs the array of contacts containing services
+     * @param filter a predicate function to filter services: (service, contact) => boolean
+     * @return a promise containing an array of filtered services
+     */
     filterServices(ctcs, filter) {
         return Promise.resolve(this.filteredServices(ctcs, filter));
     }
+    /**
+     * Gets all services from a contact that have the specified label.
+     * @param ctc the contact
+     * @param label the service label to filter by
+     * @return an array of services with the given label
+     */
     services(ctc, label) {
         return ctc.services.filter((s) => s.label === label);
     }
+    /**
+     * Gets the preferred content for a service based on language preference, falling back to French then first available language.
+     * @param svc the service
+     * @param lng the preferred language code
+     * @return the content in the preferred language or null if no content exists
+     */
     preferredContent(svc, lng) {
         return (svc && svc.content && (svc.content[lng] || svc.content['fr'] || (Object.keys(svc.content)[0] ? svc.content[Object.keys(svc.content)[0]] : null)));
     }
+    /**
+     * Extracts the value from content, prioritizing string, number, measure, medication, and boolean values in that order.
+     * @param c the content
+     * @return the extracted value or undefined if no value is present
+     */
     contentValue(c) {
         return (c.stringValue ||
             ((c.numberValue || c.numberValue === 0) && c.numberValue) ||
@@ -428,10 +569,23 @@ class IccContactXApi extends icc_api_1.IccContactApi {
             c.medicationValue ||
             c.booleanValue);
     }
+    /**
+     * Gets a short human-readable description of a service in the preferred language.
+     * @param svc the service
+     * @param lng the preferred language code
+     * @return a short description of the service content or empty string
+     */
     shortServiceDescription(svc, lng) {
         const c = this.preferredContent(svc, lng);
         return !c ? '' : this.shortContentDescription(c, lng, svc.label);
     }
+    /**
+     * Gets a short human-readable description of content, formatted appropriately for the content type.
+     * @param c the content
+     * @param lng the language code for medication formatting
+     * @param label optional label used for boolean content display
+     * @return a short description of the content
+     */
     shortContentDescription(c, lng, label) {
         return (c.stringValue ||
             ((c.numberValue || c.numberValue === 0) && c.numberValue) ||
@@ -443,13 +597,30 @@ class IccContactXApi extends icc_api_1.IccContactApi {
             (c.booleanValue && label) ||
             'OK');
     }
+    /**
+     * Extracts the medication value from a service's content in the preferred language.
+     * @param svc the service
+     * @param lng the preferred language code
+     * @return the medication value or undefined if not present
+     */
     medicationValue(svc, lng) {
         const c = svc && svc.content && (svc.content[lng] || svc.content['fr'] || (Object.keys(svc.content)[0] ? svc.content[Object.keys(svc.content)[0]] : null));
         return c && c.medicationValue;
     }
+    /**
+     * Checks if content has any data value set (string, number, measure, boolean, medication, or document).
+     * @param c the content to check
+     * @return true if content has data, false otherwise
+     */
     contentHasData(c) {
         return c.stringValue || c.numberValue || c.measureValue || c.booleanValue || c.booleanValue === false || c.medicationValue || c.documentId;
     }
+    /**
+     * Localizes a value by selecting the appropriate language from an object, falling back through FR, EN, and NL.
+     * @param e the object with language-keyed values or a simple value
+     * @param lng the preferred language code
+     * @return the localized value or null if e is null/undefined
+     */
     localize(e, lng) {
         if (!e) {
             return null;
@@ -567,10 +738,20 @@ class IccContactXApi extends icc_api_1.IccContactApi {
         });
         return (init && init(promoted)) || promoted;
     }
+    /**
+     * Checks if a service has numeric content (measure or number value) in the preferred language.
+     * @param svc the service
+     * @param lng the preferred language code
+     * @return true if the service has numeric content, false otherwise
+     */
     isNumeric(svc, lng) {
         const c = this.preferredContent(svc, lng);
         return c && (c.measureValue || c.numberValue || c.numberValue == 0);
     }
+    /**
+     * Returns utility functions for working with services.
+     * @return an object with helper methods for creating and manipulating services
+     */
     service() {
         return {
             newInstance: (user, s) => {
@@ -590,6 +771,10 @@ class IccContactXApi extends icc_api_1.IccContactApi {
             },
         };
     }
+    /**
+     * Returns utility functions for working with medication content.
+     * @return an object with helper methods for formatting and displaying medication information
+     */
     medication() {
         const regimenScores = {
             afterwakingup: 63000,
@@ -838,24 +1023,56 @@ class IccContactXApi extends icc_api_1.IccContactApi {
                 .then((r) => r.mapSuccessAsync((e) => this.decrypt(self, [e]).then((es) => es[0])));
         });
     }
+    /**
+     * Gets the data owners that have access to the contact and their permission levels.
+     * @param entity the contact
+     * @return a promise containing the permissions by data owner id and whether there are unknown anonymous data owners
+     */
     getDataOwnersWithAccessTo(entity) {
         return this.crypto.delegationsDeAnonymization.getDataOwnersWithAccessTo({ entity, type: utils_1.EntityWithDelegationTypeName.Contact });
     }
+    /**
+     * Gets all encryption keys available for the contact.
+     * @param entity the contact
+     * @return a promise containing an array of encryption key hex strings
+     */
     getEncryptionKeysOf(entity) {
         return this.crypto.xapi.encryptionKeysOf({ entity, type: utils_1.EntityWithDelegationTypeName.Contact }, undefined);
     }
+    /**
+     * Subscribes to service events (create, update, delete) and receives decrypted services.
+     * @param eventTypes the types of events to subscribe to
+     * @param filter optional filter to apply to services
+     * @param eventFired callback function invoked when an event occurs, receives the decrypted service
+     * @param options optional subscription options
+     * @return a connection that can be closed to unsubscribe
+     */
     subscribeToServiceEvents(eventTypes_1, filter_1, eventFired_1) {
         return __awaiter(this, arguments, void 0, function* (eventTypes, filter, eventFired, options = {}) {
             const currentUser = yield this.userApi.getCurrentUser();
             return (0, utils_1.subscribeToEntityEvents)(this.host, this.authApi, 'Service', eventTypes, filter, eventFired, options, (encrypted) => __awaiter(this, void 0, void 0, function* () { return (yield this.decryptServices(currentUser.healthcarePartyId, [encrypted]))[0]; })).then((ws) => new Connection_1.ConnectionImpl(ws));
         });
     }
+    /**
+     * Subscribes to contact events (create, update, delete) and receives decrypted contacts.
+     * @param eventTypes the types of events to subscribe to
+     * @param filter optional filter to apply to contacts
+     * @param eventFired callback function invoked when an event occurs, receives the decrypted contact
+     * @param options optional subscription options
+     * @return a connection that can be closed to unsubscribe
+     */
     subscribeToContactEvents(eventTypes_1, filter_1, eventFired_1) {
         return __awaiter(this, arguments, void 0, function* (eventTypes, filter, eventFired, options = {}) {
             const currentUser = yield this.userApi.getCurrentUser();
             return (0, utils_1.subscribeToEntityEvents)(this.host, this.authApi, utils_1.EntityWithDelegationTypeName.Contact, eventTypes, filter, eventFired, options, (encrypted) => __awaiter(this, void 0, void 0, function* () { return (yield this.decrypt(currentUser.healthcarePartyId, [encrypted]))[0]; })).then((ws) => new Connection_1.ConnectionImpl(ws));
         });
     }
+    /**
+     * Creates or updates de-anonymization metadata for delegations in a contact.
+     * @param entity the contact
+     * @param delegates the array of delegate ids to create de-anonymization metadata for
+     * @return a promise that completes when the metadata is created/updated
+     */
     createDelegationDeAnonymizationMetadata(entity, delegates) {
         return this.crypto.delegationsDeAnonymization.createOrUpdateDeAnonymizationInfo({ entity, type: utils_1.EntityWithDelegationTypeName.Contact }, delegates);
     }