doc(hd-wallet): expose api doc (#2186)

* doc(hd-wallet): expose api doc

* chore(hd-wallet): format

.changeset/happy-hornets-turn.md

@@ -0,0 +1,5 @@
+---
+"@kadena/hd-wallet": patch
+---
+
+Expose api doc

packages/libs/hd-wallet/etc/hd-wallet.api.md

@@ -0,0 +1,68 @@
+## API Report File for "@kadena/hd-wallet"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { EncryptedString as EncryptedString_2 } from '../utils/kadenaEncryption.js';
+
+// @public (undocumented)
+export type EncryptedString = string & {
+    _brand: 'EncryptedString';
+};
+
+// Warning: (ae-forgotten-export) The symbol "BinaryLike" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function kadenaChangePassword(password: BinaryLike, encryptedData: BinaryLike, newPassword: string): Promise<EncryptedString>;
+
+// @public
+export function kadenaDecrypt(password: BinaryLike, encryptedData: BinaryLike): Promise<Uint8Array>;
+
+// @public
+export function kadenaEncrypt<TEncode extends 'base64' | 'buffer' = 'base64', TReturn = TEncode extends 'base64' ? EncryptedString : Uint8Array>(password: BinaryLike, message: BinaryLike, encode?: TEncode): Promise<TReturn>;
+
+// @public (undocumented)
+export function kadenaGenKeypairFromSeed(password: BinaryLike, seed: EncryptedString, index: number, derivationPathTemplate?: string): Promise<[string, EncryptedString]>;
+
+// @public (undocumented)
+export function kadenaGenKeypairFromSeed(password: BinaryLike, seed: EncryptedString, indexRange: [number, number], derivationPathTemplate?: string): Promise<Array<[string, EncryptedString]>>;
+
+// @public
+export function kadenaGenMnemonic(): string;
+
+// @public (undocumented)
+export function kadenaGetPublic(password: BinaryLike, seed: BinaryLike, index: number, derivationPathTemplate?: string): Promise<string>;
+
+// @public (undocumented)
+export function kadenaGetPublic(password: BinaryLike, seed: BinaryLike, indexRange: [number, number], derivationPathTemplate?: string): Promise<string[]>;
+
+// @public
+export function kadenaKeyPairsFromRandom(count?: number): {
+    publicKey: string;
+    secretKey: string;
+}[];
+
+// @public
+export function kadenaMnemonicToSeed<TEncode extends 'base64' | 'buffer' = 'base64'>(password: BinaryLike, mnemonic: string, encode?: TEncode): Promise<TEncode extends "base64" ? EncryptedString_2 : Uint8Array>;
+
+// Warning: (ae-forgotten-export) The symbol "ISignatureWithPublicKey" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function kadenaSignWithKeyPair(password: BinaryLike, publicKey: string, encryptedPrivateKey: EncryptedString): (hash: string) => Promise<ISignatureWithPublicKey>;
+
+// @public
+export function kadenaSignWithSeed(password: BinaryLike, seed: BinaryLike, index: number, derivationPathTemplate?: string): (hash: string) => Promise<ISignatureWithPublicKey>;
+
+// @public
+export function kadenaSignWithSeed(password: BinaryLike, seed: BinaryLike, indexRange: number[], derivationPathTemplate?: string): (hash: string) => Promise<ISignatureWithPublicKey[]>;
+
+// @public
+export function kadenaVerify(message: BinaryLike, publicKey: string, signature: string): boolean;
+
+// @public (undocumented)
+export const randomBytes: (size: number) => Uint8Array;
+
+// (No @packageDocumentation comment for this package)
+
+```

packages/libs/hd-wallet/package.json

@@ -37,7 +37,7 @@
     "chainweaver"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.cjs.json && tsc && api-extractor run || true && cpy ./src/chainweaver/vendor/**/* ./lib/cjs/chainweaver/vendor/ && cpy ./src/chainweaver/vendor/**/* ./lib/esm/chainweaver/vendor/ && cp ./package.cjs.json ./lib/cjs/package.json",
+    "build": "tsc -p tsconfig.cjs.json && tsc && api-extractor run && cpy ./src/chainweaver/vendor/**/* ./lib/cjs/chainweaver/vendor/ && cpy ./src/chainweaver/vendor/**/* ./lib/esm/chainweaver/vendor/ && cp ./package.cjs.json ./lib/cjs/package.json",
     "format": "pnpm run --sequential /^format:.*/",
     "format:lint": "pnpm run lint:src --fix",
     "format:md": "remark README.md -o --use @kadena-dev/markdown",

packages/libs/hd-wallet/src/SLIP10/kadenaGenKeypairFromSeed.ts

@@ -30,11 +30,11 @@ async function genKeypairFromSeed(
 
 /**
  *
- * @param password
- * @param seed
- * @param index
- * @param derivationPathTemplate
- * @alpha
+ * @param password - password for decrypting the seed
+ * @param seed - encrypted seed to generate keypair
+ * @param index - index to generate keypair
+ * @param derivationPathTemplate - derivation path template
+ * @public
  */
 export function kadenaGenKeypairFromSeed(
   password: BinaryLike,
@@ -43,6 +43,14 @@ export function kadenaGenKeypairFromSeed(
   derivationPathTemplate?: string,
 ): Promise<[string, EncryptedString]>;
 
+/**
+ *
+ * @param password - password for decrypting the seed
+ * @param seed - encrypted seed to generate keypair
+ * @param indexRange - range of indices to generate keypair
+ * @param derivationPathTemplate - derivation path template
+ * @public
+ */
 export function kadenaGenKeypairFromSeed(
   password: BinaryLike,
   seed: EncryptedString,

packages/libs/hd-wallet/src/SLIP10/kadenaGetPublic.ts

@@ -22,13 +22,29 @@ function genPublicKeyFromSeed(
   return publicKey;
 }
 
+/**
+ *
+ * @param password - password for decrypting the seed
+ * @param seed - encrypted seed to generate keypair
+ * @param index - index to generate public key
+ * @param derivationPathTemplate - derivation path template
+ * @public
+ */
 export function kadenaGetPublic(
   password: BinaryLike,
   seed: BinaryLike,
   index: number,
   derivationPathTemplate?: string,
 ): Promise<string>;
 
+/**
+ *
+ * @param password - password for decrypting the seed
+ * @param seed - encrypted seed to generate keypair
+ * @param indexRange - range of indices to generate public keys
+ * @param derivationPathTemplate - derivation path template
+ * @public
+ */
 export function kadenaGetPublic(
   password: BinaryLike,
   seed: BinaryLike,

packages/libs/hd-wallet/src/SLIP10/kadenaKeyPairsFromRandom.ts

@@ -3,8 +3,9 @@ import { deriveKeyPair } from './utils/sign.js';
 /**
  * Generates random key pairs without updating the internal state.
  *
- * @param {number} [count=1] - The number of key pairs to generate.
- * @returns {{ publicKey: string; secretKey: string }[]} An array of generated key pairs.
+ * @param count - The number of key pairs to generate default is `1`.
+ * @returns An array of generated key pairs.
+ * @public
  */
 export function kadenaKeyPairsFromRandom(
   count: number = 1,

packages/libs/hd-wallet/src/SLIP10/kadenaMnemonic.ts

@@ -5,8 +5,9 @@ import { kadenaEncrypt } from '../utils/kadenaEncryption.js';
 /**
  * Generates a mnemonic phrase using the BIP39 protocol with a specified wordlist.
  *
- * @returns {string} A valid BIP39 mnemonic phrase.
- * @throws {Error} If the generated mnemonic is invalid.
+ * @returns A valid BIP39 mnemonic phrase.
+ * @throws If the generated mnemonic is invalid.
+ * @public
  */
 export function kadenaGenMnemonic(): string {
   return bip39.generateMnemonic(wordlist);
@@ -15,10 +16,11 @@ export function kadenaGenMnemonic(): string {
 /**
  * Convert a given mnemonic phrase into a seed buffer.
  *
- * @param {string} mnemonic - A mnemonic seed phrase to be converted into a seed buffer.
- * @param {string} [password] - Optional password for encrypting the seed.
- * @throws {Error} Throws an error if the provided mnemonic is not valid.
- * @returns {Promise<{ seedBuffer: Uint8Array, seed: string }>} - Returns the seed buffer and processed seed.
+ * @param mnemonic - A mnemonic seed phrase to be converted into a seed buffer.
+ * @param password - Optional password for encrypting the seed.
+ * @throws Throws an error if the provided mnemonic is not valid.
+ * @returns Returns the seed buffer and processed seed.
+ * @public
  */
 export async function kadenaMnemonicToSeed<
   TEncode extends 'base64' | 'buffer' = 'base64',

packages/libs/hd-wallet/src/SLIP10/kadenaSign.ts

@@ -9,9 +9,10 @@ import { signWithKeyPair, signWithSeed } from './utils/sign.js';
 /**
  * Signs a Kadena transaction with a given public and private key pair.
  *
- * @param {string} publicKey - The public key to be used for signing the transaction.
- * @param {string} encryptedPrivateKey - The private key to be used for signing the transaction.
- * @returns {Function} A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures.
+ * @param publicKey - The public key to be used for signing the transaction.
+ * @param encryptedPrivateKey - The private key to be used for signing the transaction.
+ * @returns A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures.
+ * @public
  */
 export function kadenaSignWithKeyPair(
   password: BinaryLike,
@@ -31,26 +32,42 @@ export function kadenaSignWithKeyPair(
     )(hash);
 }
 
+/**
+ * Signs a Kadena transaction with a seed and index.
+ *
+ * @param seed - The encrypted seed used to derive key pairs for signing.
+ * @param index - The index number used to select the correct key pair from the derived set.
+ * @returns A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures.
+ * @public
+ */
 export function kadenaSignWithSeed(
   password: BinaryLike,
   seed: BinaryLike,
   index: number,
   derivationPathTemplate?: string,
 ): (hash: string) => Promise<ISignatureWithPublicKey>;
 
+/**
+ * Signs a Kadena transaction with a seed and index.
+ *
+ * @param seed - The encrypted seed used to derive key pairs for signing.
+ * @param indexRange - The index range used to select the correct key pair from the derived set.
+ * @returns A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures.
+ * @public
+ */
 export function kadenaSignWithSeed(
   password: BinaryLike,
   seed: BinaryLike,
-  index: number[],
+  indexRange: number[],
   derivationPathTemplate?: string,
 ): (hash: string) => Promise<ISignatureWithPublicKey[]>;
 
 /**
  * Signs a Kadena transaction with a seed and index.
  *
- * @param {Uint8Array} seed - The seed array used to derive key pairs for signing.
- * @param {number} index - The index number used to select the correct key pair from the derived set.
- * @returns {Function} A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures.
+ * @param seed - The seed array used to derive key pairs for signing.
+ * @param index - The index number used to select the correct key pair from the derived set.
+ * @returns A function that takes an unsigned command (`IUnsignedCommand`) and returns an object with an array of signatures.
  */
 export function kadenaSignWithSeed(
   password: BinaryLike,
@@ -88,10 +105,11 @@ export function kadenaSignWithSeed(
 /**
  * Verifies the signature for a message against a given public key using the Kadena signature verification convention.
  *
- * @param {string} message - The message in string format to be verified.
- * @param {string} publicKey - The public key in hexadecimal string format to verify the signature against.
- * @param {string} signature - The signature in hexadecimal string format to be verified.
- * @returns {boolean} - Returns true if verification succeeded or false if it failed.
+ * @param message - The message in string format to be verified.
+ * @param publicKey - The public key in hexadecimal string format to verify the signature against.
+ * @param signature - The signature in hexadecimal string format to be verified.
+ * @returns Returns true if verification succeeded or false if it failed.
+ * @public
  */
 export function kadenaVerify(
   message: BinaryLike,

packages/libs/hd-wallet/src/SLIP10/utils/sign.ts

@@ -9,10 +9,11 @@ export interface ISignatureWithPublicKey {
 }
 
 /**
- * Derive a key pair using a seed and an index.
- * @param {Uint8Array} seed - The seed for key derivation.
- * @param {number} index - The index for key derivation.
- * @returns {{ privateKey: string; publicKey: string }} - Returns the derived private and public keys.
+ * Derive a key pair using a seed and an index. the seed need to be decrypted before using this function.
+ * @param seed - The seed for key derivation.
+ * @param index - The index for key derivation.
+ * @returns Returns the derived private and public keys.
+ * @internal
  */
 export const deriveKeyPair = (
   seed: Uint8Array,

packages/libs/hd-wallet/src/utils/crypto.ts

@@ -1,5 +1,11 @@
 export type BinaryLike = string | ArrayBuffer | Uint8Array;
 
+/**
+ *
+ * @param size - size of random bytes
+ * @returns Uint8Array of random bytes
+ * @public
+ */
 export const randomBytes = (size: number) =>
   crypto.getRandomValues(new Uint8Array(size));
 

packages/libs/hd-wallet/src/utils/kadenaEncryption.ts

@@ -1,13 +1,17 @@
 import type { BinaryLike } from './crypto.js';
 import { decrypt, encrypt, randomBytes } from './crypto.js';
 
+/**
+ * @public
+ */
 export type EncryptedString = string & { _brand: 'EncryptedString' };
 
 /**
  * Encrypts the message with a password .
- * @param {BinaryLike} message - The message to be encrypted.
- * @param {BinaryLike} password - password used for encryption.
- * @returns {string} The encrypted string
+ * @param message - The message to be encrypted.
+ * @param password - password used for encryption.
+ * @returns The encrypted string
+ * @public
  */
 export async function kadenaEncrypt<
   TEncode extends 'base64' | 'buffer' = 'base64',
@@ -41,11 +45,11 @@ export async function kadenaEncrypt<
  * This function is a wrapper for the internal decryption logic, intended
  * for public-facing API usage where the private key encryption follows
  *
- * @param {string} encryptedData - The encrypted data as a Base64 encoded string.
- * @param {BinaryLike} password - The password used to encrypt the private key.
- * @returns {Uint8Array} The decrypted private key.
- * @throws {Error} Throws an error if decryption fails.
- * @alpha
+ * @param encryptedData - The encrypted data as a Base64 encoded string.
+ * @param password - The password used to encrypt the private key.
+ * @returns The decrypted private key.
+ * @throws Throws an error if decryption fails.
+ * @public
  */
 export async function kadenaDecrypt(
   password: BinaryLike,
@@ -78,11 +82,12 @@ export async function kadenaDecrypt(
 /**
  * Changes the password of an encrypted data.
  *
- * @param {string} privateKey - The encrypted private key as a Base64 encoded string.
- * @param {BinaryLike} password - The current password used to encrypt the private key.
- * @param {string} newPassword - The new password to encrypt the private key with.
- * @returns {string} - The newly encrypted private key as a Base64 encoded string.
- * @throws {Error} - Throws an error if the old password is empty, new password is incorrect empty passwords are empty, or if encryption with the new password fails.
+ * @param privateKey - The encrypted private key as a Base64 encoded string.
+ * @param password - The current password used to encrypt the private key.
+ * @param newPassword - The new password to encrypt the private key with.
+ * @returns The newly encrypted private key as a Base64 encoded string.
+ * @throws Throws an error if the old password is empty, new password is incorrect empty passwords are empty, or if encryption with the new password fails.
+ * @public
  */
 export async function kadenaChangePassword(
   password: BinaryLike,