@icure/api 8.6.5 → 8.6.7

package/icc-x-api/icc-helement-x-api.d.ts

@@ -52,23 +52,98 @@ export declare class IccHelementXApi extends IccHelementApi implements Encrypted
         ignoreAutoDelegations?: boolean;
         alternateRootDelegation?: string;
     }): Promise<models.HealthElement>;
+    /**
+     * @throws always. Use {@link createHealthElementWithUser} instead.
+     */
     createHealthElement(body?: models.HealthElement): never;
+    /**
+     * Creates a health element after encrypting its content.
+     * @param user the current user, used for encryption.
+     * @param body the health element to create.
+     * @return the created and decrypted health element.
+     */
     createHealthElementWithUser(user: models.User, body?: models.HealthElement): Promise<models.HealthElement | any>;
+    /**
+     * @throws always. Use {@link createHealthElementsWithUser} instead.
+     */
     createHealthElements(body?: Array<HealthElement>): never;
+    /**
+     * Creates multiple health elements after encrypting their content.
+     * @param user the current user, used for encryption.
+     * @param bodies the health elements to create.
+     * @return the created and decrypted health elements.
+     */
     createHealthElementsWithUser(user: models.User, bodies?: models.HealthElement[]): Promise<models.HealthElement[] | any>;
+    /**
+     * @throws always. Use {@link getHealthElementWithUser} instead.
+     */
     getHealthElement(healthElementId: string): never;
+    /**
+     * Retrieves a health element by id and decrypts it.
+     * @param user the current user, used for decryption.
+     * @param healthElementId the id of the health element to retrieve.
+     * @return the decrypted health element.
+     */
     getHealthElementWithUser(user: models.User, healthElementId: string): Promise<models.HealthElement>;
+    /**
+     * @throws always. Use {@link getHealthElementsWithUser} instead.
+     */
     getHealthElements(body?: models.ListOfIds): never;
+    /**
+     * Retrieves multiple health elements by their ids and decrypts them.
+     * @param user the current user, used for decryption.
+     * @param body the list of health element ids to retrieve.
+     * @return the decrypted health elements.
+     */
     getHealthElementsWithUser(user: models.User, body?: models.ListOfIds): Promise<models.HealthElement[]>;
+    /**
+     * @throws always.
+     */
     newHealthElementDelegations(healthElementId: string, body?: Array<models.Delegation>): never;
+    /**
+     * @throws always. Use {@link findHealthElementsByHCPartyPatientForeignKeysWithUser} instead.
+     */
     findHealthElementsByHCPartyPatientForeignKeys(hcPartyId: string, secretFKeys: string): never;
+    /**
+     * @deprecated use {@link findHealthElementIdsByDataOwnerPatientOpeningDate} instead.
+     */
     findHealthElementsByHCPartyPatientForeignKeysWithUser(user: models.User, hcPartyId: string, secretFKeys: string): Promise<HealthElement[]>;
+    /**
+     * @deprecated use {@link findHealthElementIdsByDataOwnerPatientOpeningDate} instead.
+     */
     findHealthElementsByHCPartyPatientForeignKeysArrayWithUser(user: models.User, hcPartyId: string, secretFKeys: string[]): Promise<HealthElement[]>;
+    /**
+     * Finds all health elements for a given patient and healthcare party, and decrypts them.
+     * @deprecated use {@link findHealthElementIdsByDataOwnerPatientOpeningDate} instead.
+     * @param user the current user, used for decryption.
+     * @param hcPartyId the id of the healthcare party.
+     * @param patient the patient whose health elements to find.
+     * @param usingPost if true, uses POST instead of GET for the request.
+     * @return the decrypted health elements.
+     */
     findHealthElementsByHCPartyAndPatientWithUser(user: models.User, hcPartyId: string, patient: models.Patient, usingPost?: boolean): Promise<models.HealthElement[]>;
+    /**
+     * @throws always. Use {@link modifyHealthElementWithUser} instead.
+     */
     modifyHealthElement(body?: HealthElement): never;
+    /**
+     * Modifies a health element after encrypting its content.
+     * @param user the current user, used for encryption/decryption.
+     * @param body the health element with updated fields.
+     * @return the modified and decrypted health element, or null if body was not provided.
+     */
     modifyHealthElementWithUser(user: models.User, body?: HealthElement): Promise<HealthElement | any>;
     private modifyHealthElementAs;
+    /**
+     * @throws always. Use {@link modifyHealthElementsWithUser} instead.
+     */
     modifyHealthElements(body?: Array<HealthElement>): never;
+    /**
+     * Modifies multiple health elements after encrypting their content.
+     * @param user the current user, used for encryption/decryption.
+     * @param bodies the health elements with updated fields.
+     * @return the modified and decrypted health elements, or null if bodies was not provided.
+     */
     modifyHealthElementsWithUser(user: models.User, bodies?: HealthElement[]): Promise<HealthElement[] | any>;
     /**
      * 1. Check whether there is a delegation with 'hcpartyId' or not.
@@ -102,13 +177,55 @@ export declare class IccHelementXApi extends IccHelementApi implements Encrypted
      * @deprecated use {@link findHealthElementIdsByDataOwnerPatientOpeningDate} instead.
      */
     findByHCPartyPatientSecretFKeysArray(hcPartyId: string, secretFKeys: string[]): Promise<Array<models.Contact> | any>;
+    /**
+     * Encrypts the encrypted fields of a list of health elements.
+     * @param user the current user, used to determine the data owner for encryption.
+     * @param healthElements the health elements to encrypt.
+     * @return the encrypted health elements.
+     */
     encrypt(user: models.User, healthElements: Array<models.HealthElement>): Promise<Array<models.HealthElement>>;
     private encryptAs;
+    /**
+     * Decrypts a list of health elements using the given user's data owner keys.
+     * @param user the current user.
+     * @param hes the health elements to decrypt.
+     * @return the decrypted health elements.
+     */
     decryptWithUser(user: models.User, hes: Array<models.HealthElement>): Promise<Array<models.HealthElement>>;
+    /**
+     * Decrypts a list of health elements using the current data owner's keys.
+     * @param dataOwnerId the id of the data owner performing the decryption.
+     * @param hes the health elements to decrypt.
+     * @return the decrypted health elements.
+     */
     decrypt(dataOwnerId: string, hes: Array<models.HealthElement>): Promise<Array<models.HealthElement>>;
+    /**
+     * @throws always. Use {@link filterByWithUser} instead.
+     */
     filterHealthElementsBy(startDocumentId?: string, limit?: number, body?: FilterChainHealthElement): never;
+    /**
+     * Filters health elements using the provided filter chain and decrypts the results.
+     * @param user the current user, used for decryption.
+     * @param startDocumentId the pagination start document id.
+     * @param limit the maximum number of results to return.
+     * @param body the filter chain to apply.
+     * @return a paginated list of decrypted health elements.
+     */
     filterByWithUser(user: models.User, startDocumentId?: string, limit?: number, body?: FilterChainHealthElement): Promise<PaginatedListHealthElement>;
+    /**
+     * Converts a service into a new health element linked to the given patient.
+     * @param user the current user.
+     * @param patient the patient to link the health element to.
+     * @param heSvc the service to convert.
+     * @param descr the description for the new health element.
+     * @return the created health element.
+     */
     serviceToHealthElement(user: models.User, patient: models.Patient, heSvc: models.Service, descr: string): Promise<never>;
+    /**
+     * Parses a pipe-delimited code string into a Code object.
+     * @param code the code string in format "type|code|version".
+     * @return a Code object with the parsed fields.
+     */
     stringToCode(code: string): models.Code;
     /**
      * @param healthElement a health element
@@ -187,13 +304,37 @@ export declare class IccHelementXApi extends IccHelementApi implements Encrypted
             sharePatientId?: ShareMetadataBehaviour;
         };
     }): Promise<ShareResult<models.HealthElement>>;
+    /**
+     * Retrieves the data owners that have access to the given health element, along with their access levels.
+     * @param entity the health element.
+     * @return an object containing a map of data owner ids to their access levels, and a flag indicating if there are unknown anonymous data owners.
+     */
     getDataOwnersWithAccessTo(entity: models.HealthElement): Promise<{
         permissionsByDataOwnerId: {
             [p: string]: AccessLevelEnum;
         };
         hasUnknownAnonymousDataOwners: boolean;
     }>;
+    /**
+     * Retrieves the encryption keys of the given health element.
+     * @param entity the health element.
+     * @return the encryption key ids.
+     */
     getEncryptionKeysOf(entity: models.HealthElement): Promise<string[]>;
+    /**
+     * Subscribes to real-time health element events using a WebSocket connection. Received events are automatically decrypted.
+     * @param eventTypes the types of events to listen for (e.g. 'CREATE', 'UPDATE', 'DELETE').
+     * @param filter an optional filter to restrict which health element events trigger the callback.
+     * @param eventFired the callback function invoked when a matching health element event is received.
+     * @param options optional subscription configuration such as connection parameters and retry behaviour.
+     * @return a connection object that can be used to manage the WebSocket subscription lifecycle.
+     */
     subscribeToHealthElementEvents(eventTypes: ('CREATE' | 'UPDATE' | 'DELETE')[], filter: AbstractFilter<HealthElement> | undefined, eventFired: (healthElement: HealthElement) => Promise<void>, options?: SubscriptionOptions): Promise<Connection>;
+    /**
+     * Creates or updates de-anonymization metadata for the given health element, allowing the specified delegates to
+     * identify the data owners that have access to it.
+     * @param entity the health element.
+     * @param delegates the data owner ids for which to create de-anonymization metadata.
+     */
     createDelegationDeAnonymizationMetadata(entity: HealthElement, delegates: string[]): Promise<void>;
 }

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

@@ -69,9 +69,18 @@ class IccHelementXApi extends icc_api_1.IccHelementApi {
             return new models.HealthElement(initialisationInfo.updatedEntity);
         });
     }
+    /**
+     * @throws always. Use {@link createHealthElementWithUser} instead.
+     */
     createHealthElement(body) {
         throw new Error('Cannot call a method that returns health elements without providing a user for de/encryption');
     }
+    /**
+     * Creates a health element after encrypting its content.
+     * @param user the current user, used for encryption.
+     * @param body the health element to create.
+     * @return the created and decrypted health element.
+     */
     createHealthElementWithUser(user, body) {
         return body
             ? this.encrypt(user, [_.cloneDeep(body)])
@@ -80,9 +89,18 @@ class IccHelementXApi extends icc_api_1.IccHelementApi {
                 .then((hes) => hes[0])
             : Promise.resolve(null);
     }
+    /**
+     * @throws always. Use {@link createHealthElementsWithUser} instead.
+     */
     createHealthElements(body) {
         throw new Error('Cannot call a method that returns health elements without providing a user for de/encryption');
     }
+    /**
+     * Creates multiple health elements after encrypting their content.
+     * @param user the current user, used for encryption.
+     * @param bodies the health elements to create.
+     * @return the created and decrypted health elements.
+     */
     createHealthElementsWithUser(user, bodies) {
         return bodies
             ? this.encrypt(user, bodies.map((c) => _.cloneDeep(c)))
@@ -90,33 +108,72 @@ class IccHelementXApi extends icc_api_1.IccHelementApi {
                 .then((hes) => this.decrypt(this.dataOwnerApi.getDataOwnerIdOf(user), hes))
             : Promise.resolve(null);
     }
+    /**
+     * @throws always. Use {@link getHealthElementWithUser} instead.
+     */
     getHealthElement(healthElementId) {
         throw new Error('Cannot call a method that returns health element without providing a user for de/encryption');
     }
+    /**
+     * Retrieves a health element by id and decrypts it.
+     * @param user the current user, used for decryption.
+     * @param healthElementId the id of the health element to retrieve.
+     * @return the decrypted health element.
+     */
     getHealthElementWithUser(user, healthElementId) {
         return super
             .getHealthElement(healthElementId)
             .then((he) => this.decryptWithUser(user, [he]))
             .then((hes) => hes[0]);
     }
+    /**
+     * @throws always. Use {@link getHealthElementsWithUser} instead.
+     */
     getHealthElements(body) {
         throw new Error('Cannot call a method that returns health elements without providing a user for de/encryption');
     }
+    /**
+     * Retrieves multiple health elements by their ids and decrypts them.
+     * @param user the current user, used for decryption.
+     * @param body the list of health element ids to retrieve.
+     * @return the decrypted health elements.
+     */
     getHealthElementsWithUser(user, body) {
         return super.getHealthElements(body).then((hes) => this.decrypt(this.dataOwnerApi.getDataOwnerIdOf(user), hes));
     }
+    /**
+     * @throws always.
+     */
     newHealthElementDelegations(healthElementId, body) {
         throw new Error('Cannot call a method that returns health element without providing a user for de/encryption');
     }
+    /**
+     * @throws always. Use {@link findHealthElementsByHCPartyPatientForeignKeysWithUser} instead.
+     */
     findHealthElementsByHCPartyPatientForeignKeys(hcPartyId, secretFKeys) {
         throw new Error('Cannot call a method that returns health element without providing a user for de/encryption');
     }
+    /**
+     * @deprecated use {@link findHealthElementIdsByDataOwnerPatientOpeningDate} instead.
+     */
     findHealthElementsByHCPartyPatientForeignKeysWithUser(user, hcPartyId, secretFKeys) {
         return super.findHealthElementsByHCPartyPatientForeignKeys(hcPartyId, secretFKeys).then((hes) => this.decryptWithUser(user, hes));
     }
+    /**
+     * @deprecated use {@link findHealthElementIdsByDataOwnerPatientOpeningDate} instead.
+     */
     findHealthElementsByHCPartyPatientForeignKeysArrayWithUser(user, hcPartyId, secretFKeys) {
         return super.findHealthElementsByHCPartyPatientForeignKeysUsingPost(hcPartyId, secretFKeys).then((hes) => this.decryptWithUser(user, hes));
     }
+    /**
+     * Finds all health elements for a given patient and healthcare party, and decrypts them.
+     * @deprecated use {@link findHealthElementIdsByDataOwnerPatientOpeningDate} instead.
+     * @param user the current user, used for decryption.
+     * @param hcPartyId the id of the healthcare party.
+     * @param patient the patient whose health elements to find.
+     * @param usingPost if true, uses POST instead of GET for the request.
+     * @return the decrypted health elements.
+     */
     findHealthElementsByHCPartyAndPatientWithUser(user_1, hcPartyId_1, patient_1) {
         return __awaiter(this, arguments, void 0, function* (user, hcPartyId, patient, usingPost = false) {
             var _a;
@@ -130,9 +187,18 @@ class IccHelementXApi extends icc_api_1.IccHelementApi {
                 : this.findHealthElementsByHCPartyPatientForeignKeysWithUser(user, hcPartyId, keys.join(','));
         });
     }
+    /**
+     * @throws always. Use {@link modifyHealthElementWithUser} instead.
+     */
     modifyHealthElement(body) {
         throw new Error('Cannot call a method that returns health element without providing a user for de/encryption');
     }
+    /**
+     * Modifies a health element after encrypting its content.
+     * @param user the current user, used for encryption/decryption.
+     * @param body the health element with updated fields.
+     * @return the modified and decrypted health element, or null if body was not provided.
+     */
     modifyHealthElementWithUser(user, body) {
         return body ? this.modifyHealthElementAs(this.dataOwnerApi.getDataOwnerIdOf(user), body) : Promise.resolve(null);
     }
@@ -142,9 +208,18 @@ class IccHelementXApi extends icc_api_1.IccHelementApi {
             .then((he) => this.decrypt(dataOwner, [he]))
             .then((hes) => hes[0]);
     }
+    /**
+     * @throws always. Use {@link modifyHealthElementsWithUser} instead.
+     */
     modifyHealthElements(body) {
         throw new Error('Cannot call a method that returns health elements without providing a user for de/encryption');
     }
+    /**
+     * Modifies multiple health elements after encrypting their content.
+     * @param user the current user, used for encryption/decryption.
+     * @param bodies the health elements with updated fields.
+     * @return the modified and decrypted health elements, or null if bodies was not provided.
+     */
     modifyHealthElementsWithUser(user, bodies) {
         return bodies
             ? this.encrypt(user, bodies.map((c) => _.cloneDeep(c)))
@@ -242,28 +317,65 @@ class IccHelementXApi extends icc_api_1.IccHelementApi {
             .findHealthElementsByHCPartyPatientForeignKeysUsingPost(hcPartyId, secretFKeys)
             .then((helements) => this.decrypt(hcPartyId, helements));
     }
+    /**
+     * Encrypts the encrypted fields of a list of health elements.
+     * @param user the current user, used to determine the data owner for encryption.
+     * @param healthElements the health elements to encrypt.
+     * @return the encrypted health elements.
+     */
     encrypt(user, healthElements) {
         return this.encryptAs(this.dataOwnerApi.getDataOwnerIdOf(user), healthElements);
     }
     encryptAs(owner, healthElements) {
         return this.crypto.xapi.tryEncryptEntities(healthElements, utils_1.EntityWithDelegationTypeName.HealthElement, this.encryptedFields, false, false, (x) => new models.HealthElement(x));
     }
+    /**
+     * Decrypts a list of health elements using the given user's data owner keys.
+     * @param user the current user.
+     * @param hes the health elements to decrypt.
+     * @return the decrypted health elements.
+     */
     decryptWithUser(user, hes) {
         return this.decrypt(this.dataOwnerApi.getDataOwnerIdOf(user), hes);
     }
+    /**
+     * Decrypts a list of health elements using the current data owner's keys.
+     * @param dataOwnerId the id of the data owner performing the decryption.
+     * @param hes the health elements to decrypt.
+     * @return the decrypted health elements.
+     */
     decrypt(dataOwnerId, hes) {
         return __awaiter(this, void 0, void 0, function* () {
             return (yield this.crypto.xapi.tryDecryptEntities(hes, utils_1.EntityWithDelegationTypeName.HealthElement, (x) => new models.HealthElement(x))).map(({ entity }) => entity);
         });
     }
+    /**
+     * @throws always. Use {@link filterByWithUser} instead.
+     */
     filterHealthElementsBy(startDocumentId, limit, body) {
         throw new Error('Cannot call a method that returns health elements without providing a user for de/encryption');
     }
+    /**
+     * Filters health elements using the provided filter chain and decrypts the results.
+     * @param user the current user, used for decryption.
+     * @param startDocumentId the pagination start document id.
+     * @param limit the maximum number of results to return.
+     * @param body the filter chain to apply.
+     * @return a paginated list of decrypted health elements.
+     */
     filterByWithUser(user, startDocumentId, limit, body) {
         return super
             .filterHealthElementsBy(startDocumentId, limit, body)
             .then((pl) => this.decryptWithUser(user, pl.rows).then((dr) => Object.assign(pl, { rows: dr })));
     }
+    /**
+     * Converts a service into a new health element linked to the given patient.
+     * @param user the current user.
+     * @param patient the patient to link the health element to.
+     * @param heSvc the service to convert.
+     * @param descr the description for the new health element.
+     * @return the created health element.
+     */
     // noinspection JSUnusedGlobalSymbols
     serviceToHealthElement(user, patient, heSvc, descr) {
         return this.newInstance(user, patient, {
@@ -281,6 +393,11 @@ class IccHelementXApi extends icc_api_1.IccHelementApi {
             return this.createHealthElement(he);
         });
     }
+    /**
+     * Parses a pipe-delimited code string into a Code object.
+     * @param code the code string in format "type|code|version".
+     * @return a Code object with the parsed fields.
+     */
     // noinspection JSUnusedGlobalSymbols, JSMethodCanBeStatic
     stringToCode(code) {
         const c = code.split('|');
@@ -386,18 +503,42 @@ class IccHelementXApi extends icc_api_1.IccHelementApi {
                 .then((r) => r.mapSuccessAsync((e) => this.decrypt(self, [e]).then((es) => es[0])));
         });
     }
+    /**
+     * Retrieves the data owners that have access to the given health element, along with their access levels.
+     * @param entity the health element.
+     * @return an object containing a map of data owner ids to their access levels, and a flag indicating if there are unknown anonymous data owners.
+     */
     getDataOwnersWithAccessTo(entity) {
         return this.crypto.delegationsDeAnonymization.getDataOwnersWithAccessTo({ entity, type: utils_1.EntityWithDelegationTypeName.HealthElement });
     }
+    /**
+     * Retrieves the encryption keys of the given health element.
+     * @param entity the health element.
+     * @return the encryption key ids.
+     */
     getEncryptionKeysOf(entity) {
         return this.crypto.xapi.encryptionKeysOf({ entity, type: utils_1.EntityWithDelegationTypeName.HealthElement }, undefined);
     }
+    /**
+     * Subscribes to real-time health element events using a WebSocket connection. Received events are automatically decrypted.
+     * @param eventTypes the types of events to listen for (e.g. 'CREATE', 'UPDATE', 'DELETE').
+     * @param filter an optional filter to restrict which health element events trigger the callback.
+     * @param eventFired the callback function invoked when a matching health element event is received.
+     * @param options optional subscription configuration such as connection parameters and retry behaviour.
+     * @return a connection object that can be used to manage the WebSocket subscription lifecycle.
+     */
     subscribeToHealthElementEvents(eventTypes_1, filter_1, eventFired_1) {
         return __awaiter(this, arguments, void 0, function* (eventTypes, filter, eventFired, options = {}) {
             const currentUser = yield this.userApi.getCurrentUser();
             return yield (0, utils_1.subscribeToEntityEvents)(this.host, this.authApi, utils_1.EntityWithDelegationTypeName.HealthElement, eventTypes, filter, eventFired, options, (encrypted) => __awaiter(this, void 0, void 0, function* () { return (yield this.decrypt(this.dataOwnerApi.getDataOwnerIdOf(currentUser), [encrypted]))[0]; })).then((rs) => new Connection_1.ConnectionImpl(rs));
         });
     }
+    /**
+     * Creates or updates de-anonymization metadata for the given health element, allowing the specified delegates to
+     * identify the data owners that have access to it.
+     * @param entity the health element.
+     * @param delegates the data owner ids for which to create de-anonymization metadata.
+     */
     createDelegationDeAnonymizationMetadata(entity, delegates) {
         return this.crypto.delegationsDeAnonymization.createOrUpdateDeAnonymizationInfo({ entity, type: utils_1.EntityWithDelegationTypeName.HealthElement }, delegates);
     }