@icure/cardinal-sdk 2.1.1 → 2.1.2

package/api/ReceiptBasicInGroupApi.d.mts

@@ -2,22 +2,94 @@ import { GroupScoped } from '../model/GroupScoped.mjs';
 import { EncryptedReceipt, Receipt } from '../model/Receipt.mjs';
 import { StoredDocumentIdentifier } from '../model/StoredDocumentIdentifier.mjs';
 export interface ReceiptBasicInGroupApi {
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.deleteReceiptById]
+     */
     deleteReceiptById(entityId: GroupScoped<StoredDocumentIdentifier>): Promise<GroupScoped<StoredDocumentIdentifier>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.deleteReceiptsByIds]
+     */
     deleteReceiptsByIds(entityIds: Array<GroupScoped<StoredDocumentIdentifier>>): Promise<Array<GroupScoped<StoredDocumentIdentifier>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.purgeReceiptById]
+     */
     purgeReceiptById(entityId: GroupScoped<StoredDocumentIdentifier>): Promise<void>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.purgeReceiptsByIds]
+     */
     purgeReceiptsByIds(entityIds: Array<GroupScoped<StoredDocumentIdentifier>>): Promise<Array<GroupScoped<StoredDocumentIdentifier>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.deleteReceipt]
+     */
     deleteReceipt(receipt: GroupScoped<Receipt>): Promise<GroupScoped<StoredDocumentIdentifier>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.deleteReceipts]
+     */
     deleteReceipts(receipts: Array<GroupScoped<Receipt>>): Promise<Array<GroupScoped<StoredDocumentIdentifier>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.purgeReceipt]
+     */
     purgeReceipt(receipt: GroupScoped<Receipt>): Promise<void>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.purgeReceipts]
+     */
     purgeReceipts(receipts: Array<GroupScoped<Receipt>>): Promise<Array<GroupScoped<StoredDocumentIdentifier>>>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.createReceipt]
+     */
     createReceipt(entity: GroupScoped<EncryptedReceipt>): Promise<GroupScoped<EncryptedReceipt>>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.createReceipts]
+     */
     createReceipts(entities: Array<GroupScoped<EncryptedReceipt>>): Promise<Array<GroupScoped<EncryptedReceipt>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceiptById]
+     */
     undeleteReceiptById(entityId: GroupScoped<StoredDocumentIdentifier>): Promise<GroupScoped<EncryptedReceipt>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceiptsByIds]
+     */
     undeleteReceiptsByIds(entityIds: Array<GroupScoped<StoredDocumentIdentifier>>): Promise<Array<GroupScoped<EncryptedReceipt>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceipt]
+     */
     undeleteReceipt(receipt: GroupScoped<Receipt>): Promise<GroupScoped<EncryptedReceipt>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceipts]
+     */
     undeleteReceipts(receipts: Array<GroupScoped<EncryptedReceipt>>): Promise<Array<GroupScoped<EncryptedReceipt>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.modifyReceipt]
+     */
     modifyReceipt(entity: GroupScoped<EncryptedReceipt>): Promise<GroupScoped<EncryptedReceipt>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.modifyReceipts]
+     */
     modifyReceipts(entities: Array<GroupScoped<EncryptedReceipt>>): Promise<Array<GroupScoped<EncryptedReceipt>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.getReceipt]
+     */
     getReceipt(groupId: string, entityId: string): Promise<GroupScoped<EncryptedReceipt> | undefined>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.getReceipts]
+     */
     getReceipts(groupId: string, entityIds: Array<string>): Promise<Array<GroupScoped<EncryptedReceipt>>>;
 }

package/api/ReceiptFlavouredApi.d.mts

@@ -5,18 +5,108 @@ export interface ReceiptFlavouredApi<E extends Receipt> {
     shareWith(delegateId: string, receipt: E, options?: {
         options?: ReceiptShareOptions | undefined;
     }): Promise<E>;
+    /**
+     *
+     *  Shares an existing access log with other data owners, allowing them to access the non-encrypted data of the access log and optionally also the
+     *  encrypted content, with read-only or read-write permissions.
+     *  @param receipt the [Receipt] to share.
+     *  @param delegates associates the id of data owners which will be granted access to the entity, to the following sharing options:
+     *  - shareEncryptionKey: specifies if the encryption key of the access log should be shared with the delegate, giving access to all encrypted
+     *  content of the entity, excluding other encrypted metadata (defaults to [ShareMetadataBehaviour.IfAvailable]).
+     *  - sharePatientId: specifies if the id of the patient that this access log refers to should be shared with the delegate. Normally this would
+     *  be the same as objectId, but it is encrypted separately from it allowing you to give access to the patient id without giving access to the other
+     *  encrypted data of the access log (defaults to [ShareMetadataBehaviour.IfAvailable]).
+     *  - requestedPermissions: the requested permissions for the delegate, defaults to [ShareMetadataBehaviour.IfAvailable].
+     *  @return the updated entity.
+     *  @throws IllegalStateException if the operation was not successful.
+     */
     shareWithMany(receipt: E, delegates: {
         [key: string]: ReceiptShareOptions;
     }): Promise<E>;
+    /**
+     *
+     *  Create a new receipt. The provided receipt must have the encryption metadata initialized.
+     *  @param entity a receipt with initialized encryption metadata
+     *  @return the created receipt with updated revision.
+     *  @throws IllegalArgumentException if the encryption metadata of the input was not initialized.
+     */
     createReceipt(entity: E): Promise<E>;
+    /**
+     *
+     *  Create multiple receipts. All the provided receipts must have the encryption metadata initialized, otherwise
+     *  this method fails without doing anything.
+     *  @param entities receipts with initialized encryption metadata
+     *  @return the created receipts with updated revision.
+     *  @throws IllegalArgumentException if the encryption metadata of any receipt in the input was not initialized.
+     */
     createReceipts(entities: Array<E>): Promise<Array<E>>;
+    /**
+     *
+     *  Restores a receipt that was marked as deleted.
+     *  @param id the id of the entity
+     *  @param rev the latest revision of the entity.
+     *  @return the restored entity.
+     *  @throws RevisionConflictException if the provided revision doesn't match the latest known revision
+     */
     undeleteReceiptById(id: string, rev: string): Promise<E>;
+    /**
+     *
+     *  Restores a batch of receiptIds that were marked as deleted.
+     *  @param entityIds the ids and the revisions of the receiptIds to restore.
+     *  @return the restored receiptIds. If some entities couldn't be restored (because the user does not have access or the revision is not
+     *  up-to-date), then those entities will not be restored and will not appear in this list.
+     */
     undeleteReceiptsByIds(entityIds: Array<StoredDocumentIdentifier>): Promise<Array<E>>;
+    /**
+     *
+     *  Restores a receipt that was marked as deleted.
+     *  @param receipt the receipt to undelete
+     *  @return the restored receipt.
+     *  @throws RevisionConflictException if the provided receipt doesn't match the latest known revision
+     */
     undeleteReceipt(receipt: Receipt): Promise<E>;
+    /**
+     *
+     *  Restores a batch of receipts that were marked as deleted.
+     *  @param receipts the receipts to restore.
+     *  @return the restored receipts. If some entities couldn't be restored (because the user does not have access or the revision is not
+     *  up-to-date), then those entities will not be restored and will not appear in this list.
+     */
     undeleteReceipts(receipts: Array<Receipt>): Promise<Array<E>>;
+    /**
+     *
+     *  Modifies a receipt. You need to have write access to the entity.
+     *  Flavoured method.
+     *  @param entity a receipt with update content
+     *  @return the receipt updated with the provided content and a new revision.
+     */
     modifyReceipt(entity: E): Promise<E>;
+    /**
+     *
+     *  Modifies multiple receipts. Ignores all receipts for which you don't have write access.
+     *  Flavoured method.
+     *  @param entities receipts with update content
+     *  @return the updated receipts with a new revision.
+     */
     modifyReceipts(entities: Array<E>): Promise<Array<E>>;
+    /**
+     *
+     *  Get a receipt by its id. You must have read access to the entity. Fails if the id does not correspond to any
+     *  entity, corresponds to an entity that is not a receipt, or corresponds to an entity for which you don't have
+     *  read access.
+     *  Flavoured method.
+     *  @param entityId a receipt id.
+     *  @return the receipt with id [entityId].
+     */
     getReceipt(entityId: string): Promise<E | undefined>;
+    /**
+     *
+     *  Get multiple receipts by their ids. Ignores all ids that do not correspond to an entity, correspond to
+     *  an entity that is not a receipt, or correspond to an entity for which you don't have read access.
+     *  Flavoured method.
+     *  @param entityIds a list of receipts ids
+     *  @return all receipts that you can access with one of the provided ids.
+     */
     getReceipts(entityIds: Array<string>): Promise<Array<E>>;
     listByReference(reference: string): Promise<Array<E>>;
 }

package/api/ReceiptFlavouredInGroupApi.d.mts

@@ -5,21 +5,69 @@ import { Receipt } from '../model/Receipt.mjs';
 import { StoredDocumentIdentifier } from '../model/StoredDocumentIdentifier.mjs';
 import { ArrayWithUniqueKeys } from '../utils/ArrayWithUniqueKeys.mjs';
 export interface ReceiptFlavouredInGroupApi<E extends Receipt> {
+    /**
+     *
+     *  In-group version of [ReceiptFlavouredApi.shareWith]
+     */
     shareWith(delegate: EntityReferenceInGroup, receipt: GroupScoped<E>, options?: {
         options?: ReceiptShareOptions | undefined;
     }): Promise<GroupScoped<E>>;
+    /**
+     *
+     *  In-group version of [ReceiptFlavouredApi.shareWithMany]
+     */
     shareWithMany(receipt: GroupScoped<E>, delegates: ArrayWithUniqueKeys<{
         delegate: EntityReferenceInGroup;
         shareOptions: ReceiptShareOptions;
     }, 'delegate'>): Promise<GroupScoped<E>>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.createReceipt]
+     */
     createReceipt(entity: GroupScoped<E>): Promise<GroupScoped<E>>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.createReceipts]
+     */
     createReceipts(entities: Array<GroupScoped<E>>): Promise<Array<GroupScoped<E>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceiptById]
+     */
     undeleteReceiptById(entityId: GroupScoped<StoredDocumentIdentifier>): Promise<GroupScoped<E>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceiptsByIds]
+     */
     undeleteReceiptsByIds(entityIds: Array<GroupScoped<StoredDocumentIdentifier>>): Promise<Array<GroupScoped<E>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceipt]
+     */
     undeleteReceipt(receipt: GroupScoped<Receipt>): Promise<GroupScoped<E>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceipts]
+     */
     undeleteReceipts(receipts: Array<GroupScoped<E>>): Promise<Array<GroupScoped<E>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.modifyReceipt]
+     */
     modifyReceipt(entity: GroupScoped<E>): Promise<GroupScoped<E>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.modifyReceipts]
+     */
     modifyReceipts(entities: Array<GroupScoped<E>>): Promise<Array<GroupScoped<E>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.getReceipt]
+     */
     getReceipt(groupId: string, entityId: string): Promise<GroupScoped<E> | undefined>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.getReceipts]
+     */
     getReceipts(groupId: string, entityIds: Array<string>): Promise<Array<GroupScoped<E>>>;
 }

package/api/ReceiptInGroupApi.d.mts

@@ -13,6 +13,10 @@ import { ReceiptFlavouredInGroupApi } from './ReceiptFlavouredInGroupApi.mjs';
 export interface ReceiptInGroupApi {
     encrypted: ReceiptFlavouredInGroupApi<EncryptedReceipt>;
     tryAndRecover: ReceiptFlavouredInGroupApi<Receipt>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.withEncryptionMetadata]
+     */
     withEncryptionMetadata(groupId: string, base: DecryptedReceipt | undefined, patient: GroupScoped<Patient> | undefined, options?: {
         user?: User | undefined;
         delegates?: {
@@ -21,35 +25,139 @@ export interface ReceiptInGroupApi {
         secretId?: SecretIdUseOption;
         alternateRootDelegateId?: string | undefined;
     }): Promise<GroupScoped<DecryptedReceipt>>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.getEncryptionKeysOf]
+     */
     getEncryptionKeysOf(receipt: GroupScoped<Receipt>): Promise<Array<HexString>>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.hasWriteAccess]
+     */
     hasWriteAccess(receipt: GroupScoped<Receipt>): Promise<boolean>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.decryptPatientIdOf]
+     */
     decryptPatientIdOf(receipt: GroupScoped<Receipt>): Promise<Array<EntityReferenceInGroup>>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.createDelegationDeAnonymizationMetadata]
+     */
     createDelegationDeAnonymizationMetadata(entity: GroupScoped<Receipt>, delegates: Array<EntityReferenceInGroup>): Promise<void>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.decrypt]
+     */
     decrypt(receipts: Array<GroupScoped<EncryptedReceipt>>): Promise<Array<GroupScoped<DecryptedReceipt>>>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.tryDecrypt]
+     */
     tryDecrypt(receipts: Array<GroupScoped<EncryptedReceipt>>): Promise<Array<GroupScoped<Receipt>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.deleteReceiptById]
+     */
     deleteReceiptById(entityId: GroupScoped<StoredDocumentIdentifier>): Promise<GroupScoped<StoredDocumentIdentifier>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.deleteReceiptsByIds]
+     */
     deleteReceiptsByIds(entityIds: Array<GroupScoped<StoredDocumentIdentifier>>): Promise<Array<GroupScoped<StoredDocumentIdentifier>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.purgeReceiptById]
+     */
     purgeReceiptById(entityId: GroupScoped<StoredDocumentIdentifier>): Promise<void>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.purgeReceiptsByIds]
+     */
     purgeReceiptsByIds(entityIds: Array<GroupScoped<StoredDocumentIdentifier>>): Promise<Array<GroupScoped<StoredDocumentIdentifier>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.deleteReceipt]
+     */
     deleteReceipt(receipt: GroupScoped<Receipt>): Promise<GroupScoped<StoredDocumentIdentifier>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.deleteReceipts]
+     */
     deleteReceipts(receipts: Array<GroupScoped<Receipt>>): Promise<Array<GroupScoped<StoredDocumentIdentifier>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.purgeReceipt]
+     */
     purgeReceipt(receipt: GroupScoped<Receipt>): Promise<void>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavourlessApi.purgeReceipts]
+     */
     purgeReceipts(receipts: Array<GroupScoped<Receipt>>): Promise<Array<GroupScoped<StoredDocumentIdentifier>>>;
+    /**
+     *
+     *  In-group version of [ReceiptFlavouredApi.shareWith]
+     */
     shareWith(delegate: EntityReferenceInGroup, receipt: GroupScoped<DecryptedReceipt>, options?: {
         options?: ReceiptShareOptions | undefined;
     }): Promise<GroupScoped<DecryptedReceipt>>;
+    /**
+     *
+     *  In-group version of [ReceiptFlavouredApi.shareWithMany]
+     */
     shareWithMany(receipt: GroupScoped<DecryptedReceipt>, delegates: ArrayWithUniqueKeys<{
         delegate: EntityReferenceInGroup;
         shareOptions: ReceiptShareOptions;
     }, 'delegate'>): Promise<GroupScoped<DecryptedReceipt>>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.createReceipt]
+     */
     createReceipt(entity: GroupScoped<DecryptedReceipt>): Promise<GroupScoped<DecryptedReceipt>>;
+    /**
+     *
+     *  In-group version of [ReceiptApi.createReceipts]
+     */
     createReceipts(entities: Array<GroupScoped<DecryptedReceipt>>): Promise<Array<GroupScoped<DecryptedReceipt>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceiptById]
+     */
     undeleteReceiptById(entityId: GroupScoped<StoredDocumentIdentifier>): Promise<GroupScoped<DecryptedReceipt>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceiptsByIds]
+     */
     undeleteReceiptsByIds(entityIds: Array<GroupScoped<StoredDocumentIdentifier>>): Promise<Array<GroupScoped<DecryptedReceipt>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceipt]
+     */
     undeleteReceipt(receipt: GroupScoped<Receipt>): Promise<GroupScoped<DecryptedReceipt>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.undeleteReceipts]
+     */
     undeleteReceipts(receipts: Array<GroupScoped<DecryptedReceipt>>): Promise<Array<GroupScoped<DecryptedReceipt>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.modifyReceipt]
+     */
     modifyReceipt(entity: GroupScoped<DecryptedReceipt>): Promise<GroupScoped<DecryptedReceipt>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.modifyReceipts]
+     */
     modifyReceipts(entities: Array<GroupScoped<DecryptedReceipt>>): Promise<Array<GroupScoped<DecryptedReceipt>>>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.getReceipt]
+     */
     getReceipt(groupId: string, entityId: string): Promise<GroupScoped<DecryptedReceipt> | undefined>;
+    /**
+     *
+     *  In-group version of [ReceiptBasicFlavouredApi.getReceipts]
+     */
     getReceipts(groupId: string, entityIds: Array<string>): Promise<Array<GroupScoped<DecryptedReceipt>>>;
 }

package/api/RecoveryApi.d.mts

@@ -7,32 +7,172 @@ import { RecoveryKeySize } from '../crypto/entities/RecoveryKeySize.mjs';
 import { RecoveryResult } from '../crypto/entities/RecoveryResult.mjs';
 import { CancellablePromise } from '../utils/CancellablePromise.mjs';
 export interface RecoveryApi {
+    /**
+     *
+     *  Create recovery data for the logged user and stores it encrypted on the iCure server. This allows the user that created
+     *  it to recover all the currently available keypairs at a later time by just providing the string returned by this method to the
+     *  {@link recoverKeyPairs} method.
+     *
+     *  You can also provide an expiration time for the recovery data (through `options.lifetimeSeconds`). If you do so, the recovery dat
+     *  a will be deleted automatically after that amount seconds has passed. If you don't provide an expiration time, the recovery data
+     *  will be available until it is explicitly deleted.
+     *
+     *  This could be used to:
+     *  - Provide some sort of one-use "recovery codes" to the user, which he can use to recover his keypair if he loses
+     *    his device. In this case you should not put any expiration time on the recovery data.
+     *  - Provide a way for the user to easily "copy" the key from one device to another. In this case you should put a
+     *    short expiration time on the recovery data (a few minutes), so that it will automatically be deleted if it is
+     *    not used after all.
+     *
+     *  # Important
+     *
+     *  The recovery key must be kept secret can give access to the private key of the user, therefore it must be kept
+     *  private.
+     *
+     *  @param includeParentsKeys if true, the recovery data will also contain any available keypairs for parents data
+     *  owners.
+     *  @param lifetimeSeconds the amount of seconds the recovery data will be available. If not provided, the recovery
+     *  data will be available until it is explicitly deleted.
+     *  @param recoveryKeyOptions specifies the size of the recovery key to generate, or if it should use a precomputed
+     *  key.
+     *  @return an hexadecimal string that is the `recoveryKey` which will allow the user to recover his keypair later or
+     *  from another device. This value must be kept secret from other users. You can use this value with {@link recoverKeyPairs}
+     */
     createRecoveryInfoForAvailableKeyPairs(options?: {
         includeParentsKeys?: boolean;
         lifetimeSeconds?: number | undefined;
         recoveryKeyOptions?: RecoveryKeyOptions | undefined;
     }): Promise<RecoveryDataKey>;
+    /**
+     *
+     *  Equivalent to [KeyPairRecoverer.recoverWithRecoveryKey]
+     */
     recoverKeyPairs(recoveryKey: RecoveryDataKey, autoDelete: boolean): Promise<RecoveryResult<{
         [key: string]: {
             [key: string]: XRsaKeypair;
         };
     }>>;
+    /**
+     *
+     *  Equivalent to [KeyPairRecoverer.waitForRecoveryKey]
+     */
     recoverKeyPairsWaitingForCreation(recoveryKey: RecoveryDataKey, autoDelete: boolean, waitSeconds: number): CancellablePromise<RecoveryResult<{
         [key: string]: {
             [key: string]: XRsaKeypair;
         };
     }>>;
+    /**
+     *
+     *  Create recovery data that allows the delegate [delegateId] to recover the content of exchange data where the
+     *  current data owner (or a parent) is involved.
+     *
+     *  The recovery data always includes exchange data where the current user is the delegator and [delegateId] is the
+     *  delegate.
+     *  If [includeBiDirectional] is true the recovery data will also include exchange data where the current user is the delegate
+     *  and [delegateId] delegator
+     *  If [includeAsParent] is true the recovery data will also include exchange data between where a parent of the current data owner is the delegator
+     *  and [delegateId] is the delegate.
+     *  If both [includeBiDirectional] and [includeAsParent] are true then any exchange data where [delegateId] is the
+     *  delegator and a parent of the current data owner is the delegate is also included.
+     *
+     *  This can be useful in the following situations:
+     *  - A user lost access to his old keypair and is asking for access back to his data. This is similar to the
+     *    give-access-back mechanism, except that instead of having to verify the public key of the delegate as in the
+     *    give-access-back, the delegator has to provide the recovery key to the delegate: the delegator has to properly
+     *    identify the delegate instead of validating that the public key belongs to the delegate.
+     *  - A patient is not yet registered in the system and therefore has no keypair, but the doctor wants to already share
+     *    some data with them. The doctor can create some placeholder exchange data, encrypted only with his own key
+     *    through the {@link IccPatientXApi.forceInitializeExchangeDataToNewlyInvitedPatient} method, then create recovery data
+     *    for it and share the recovery key with the patient. The moment the patient logs in and creates his keypair he
+     *    will use the {@link recoverExchangeData} method to "complete" the placeholder exchange data.
+     *  - An hcp wants to share data with a patient that is working in keyless mode.
+     *
+     *  @param delegateId id of the delegate that needs access to his exchange data from the current data owner. This can't
+     *  be the id of the current data owner (you should instead recover the keypair).
+     *  @param lifetimeSeconds the amount of seconds the recovery data will be available. If not provided, the recovery
+     *  data will be available until it is explicitly deleted.
+     *  @param recoveryKeyOptions specifies the size of the recovery key to generate, or if it should use a precomputed
+     *  key.
+     *  @param includeBiDirectional specifies if extra exchange data should be included in the recovery data
+     *  @param includeAsParent specifies if extra exchange data should be included in the recovery data
+     *  @return an hexadecimal string that is the `recoveryKey` which will allow the delegate to gain access to the exchange data.
+     *  This value must be kept secret from users other than the current data owner and the delegate.
+     *  You can use this value with {@link recoverExchangeData}. Returns null if there is no exchange data that can be
+     *  included in the recovery info
+     */
     createExchangeDataRecoveryInfo(delegateId: string, options?: {
         lifetimeSeconds?: number | undefined;
         recoveryKeyOptions?: RecoveryKeyOptions | undefined;
         includeBiDirectional?: boolean;
         includeAsParent?: boolean;
     }): Promise<RecoveryDataKey | undefined>;
+    /**
+     *
+     *  Recover access to the exchange data obtainable from the recovery key.
+     *
+     *  The exchange data will be automatically re-encrypted with all available verified keypairs.
+     *
+     *  This will enable the current user to access the exchange data included in this recovery key without having
+     *  to call this method again, as long as one of the keypairs used for re-encryption is available.
+     *
+     *  The exchange data will be automatically deleted from the server after the process completes successfully.
+     *
+     *  @param recoveryKey the result of a call to {@link createExchangeDataRecoveryInfo} by a delegator.
+     *  @return null on success or a failure reason if the recovery data could not be used to perform the operation.
+     */
     recoverExchangeData(recoveryKey: RecoveryDataKey): Promise<RecoveryDataUseFailureReason | undefined>;
+    /**
+     *
+     *  Get the exchange data recovery information available using the provided recovery key.
+     *
+     *  This method does nothing else: if you want to use the exchange data in this SDK you will have to inject it using
+     *  the corresponding crypto api method.
+     *
+     *  Use [recoverExchangeData] if you want to make the exchange data available to future instances of the SDK using
+     *  the current user keypairs.
+     *
+     *  @param recoveryKey the result of a call to {@link createExchangeDataRecoveryInfo} by a delegator.
+     *  @param autoDelete if true, the recovery data will be deleted from the server after it could be used successfully.
+     *  This will prevent the recovery key from being used again.
+     *  @return a recovery result wrapping the exchange data included in this
+     */
     getRecoveryExchangeData(recoveryKey: RecoveryDataKey, autoDelete: boolean): Promise<RecoveryResult<Array<RawDecryptedExchangeData>>>;
+    /**
+     *
+     *  Deletes the recovery information associated to a certain recovery key. You can use this method with the recovery key for any kind of data,
+     *  regardless of how you obtained the recovery key (from the {@link createRecoveryInfoForAvailableKeyPairs} or from the
+     *  {@link createExchangeDataRecoveryInfo} methods).
+     *  If there is no data associated to the provided recovery key, this method will do nothing.
+     *  @param recoveryKey the recovery key associated to the recovery information to delete.
+     */
     purgeRecoveryInfo(recoveryKey: RecoveryDataKey): Promise<void>;
+    /**
+     *
+     *  Deletes the recovery information associated to a certain data owner, regardless of type.
+     *  @param dataOwnerId the data owner for which to delete the recovery data.
+     *  @return the number of deleted recovery information.
+     */
     purgeAllRecoveryInfoFor(dataOwnerId: string): Promise<number>;
+    /**
+     *
+     *  Deletes all key pair recovery information for a certain data owner.
+     *  @param dataOwnerId the data owner for which to delete the key pair recovery information.
+     *  @return the number of deleted key pair recovery information.
+     */
     purgeAllKeyPairRecoveryInfoFor(dataOwnerId: string): Promise<number>;
+    /**
+     *
+     *  Deletes all exchange data recovery information for a certain data owner.
+     *  @param dataOwnerId the data owner for which to delete the exchange data recovery information.
+     *  @return the number of deleted exchange data recovery information.
+     */
     purgeAllExchangeDataRecoveryInfoFor(dataOwnerId: string): Promise<number>;
+    /**
+     *
+     *  Generate a recovery key.
+     *  Allows generating a recovery key on this device and pass it to another device that will actually create the
+     *  recovery data.
+     *  @param keySize the size of the key to generate
+     */
     preGenerateRecoveryKey(keySize: RecoveryKeySize): Promise<RecoveryDataKey>;
 }

package/api/RoleApi.d.mts

@@ -1,15 +1,76 @@
 import { Role } from '../model/Role.mjs';
 export interface RoleApi {
+    /**
+     *
+     *  @return a list containing all the permissions that can be used in roles.
+     */
+    getPermissions(): Promise<Array<string>>;
+    /**
+     *
+     *  Retrieves all roles accessible in the current group, including the one that can be inherited from the parent groups.ù
+     *  @return the available roles.
+     */
     getAllRoles(): Promise<Array<Role>>;
+    /**
+     *
+     *  Retrieves all roles accessible in a specific group, including the one that can be inherited from its parent groups.
+     *  @param groupId the id of the group.
+     *  @return the accessible roles.
+     */
     getAllRolesInGroup(groupId: string): Promise<Array<Role>>;
+    /**
+     *
+     *  Retrieve a role by its [Role.id].
+     *  @param roleId the id of the role.
+     *  @return the role or null if no such role exists.
+     */
     getRole(roleId: string): Promise<Role | undefined>;
+    /**
+     *
+     *  Retrieves a batch of roles by their [Role.id]. If an id does not correspond to any role or the role is not accessible to the user
+     *  making the request, then it will be ignored.
+     *  @param rolesIds the ids of the roles to retrieve.
+     *  @return the retrieved roles.
+     */
     getRoles(rolesIds: Array<string>): Promise<Array<Role>>;
+    /**
+     *
+     *  Creates a new role.
+     *  @param name the [Role.name].
+     *  @param permissions the set of permissions that this role will grant.
+     *  @param inheritsUpTo the maximum level in the downward group hierarchy where this role can be accessed (null = any child group at
+     *  any level, 0 = only the current group can access this role, 1 = only this group and children groups can access this role, etc...)
+     *  @return the created role.
+     */
     createRole(name: string, permissions: Array<string>, options?: {
         inheritsUpTo?: number | undefined;
     }): Promise<Role>;
+    /**
+     *
+     *  Creates a new role in a specific group.
+     *  @param groupId the id of the group.
+     *  @param name the [Role.name].
+     *  @param permissions the set of permissions that this role will grant.
+     *  @param inheritsUpTo the maximum level in the downward group hierarchy where this role can be accessed (null = any child group at
+     *  any level, 0 = only the current group can access this role, 1 = only this group and children groups can access this role, etc...)
+     *  @return the created role.
+     */
     createRoleInGroup(groupId: string, name: string, permissions: Array<string>, options?: {
         inheritsUpTo?: number | undefined;
     }): Promise<Role>;
+    /**
+     *
+     *  Sets new permission for an existing role.
+     *  @param roleId the [Role.id].
+     *  @param permissions the new permissions to set.
+     *  @return the updated role.
+     */
     modifyRolePermissions(roleId: string, permissions: Array<string>): Promise<Role>;
+    /**
+     *
+     *  Permanently deletes a role.
+     *  @param roleId the [Role.id].
+     *  @param rev the most updated revision for the role.
+     */
     purgeRole(roleId: string, rev: string): Promise<void>;
 }