hive-stream 3.0.0 → 3.0.2

package/dist/utils.d.ts

@@ -1,27 +1,334 @@
-import { Client, SignedTransaction } from '@hiveio/dhive';
+import { Client, SignedTransaction, PrivateKey } from '@hiveio/dhive';
 import { ConfigInterface } from './config';
+type HiveKeyInput = string | PrivateKey;
+interface AuthorityInput {
+    weight_threshold: number;
+    account_auths: [string, number][];
+    key_auths: [string, number][];
+}
+/**
+ * Utility functions for Hive blockchain operations and general helpers
+ */
 export declare const Utils: {
-    sleep(milliseconds: number): Promise<unknown>;
-    shuffle(array: any): any;
-    roundPrecision(value: any, precision: any): number;
+    /**
+     * Pauses execution for the specified number of milliseconds
+     * @param milliseconds - The number of milliseconds to sleep
+     * @returns Promise that resolves after the specified time
+     */
+    sleep(milliseconds: number): Promise<void>;
+    normalizePrivateKeys(keys: HiveKeyInput | HiveKeyInput[]): PrivateKey[];
+    toHiveTimestamp(value: string | Date): string;
+    normalizeJsonMeta(meta?: string | Record<string, any>): string;
+    /**
+     * Shuffles an array in place using the Fisher-Yates algorithm
+     * @param array - The array to shuffle (modified in place)
+     * @returns The shuffled array
+     */
+    shuffle<T>(array: T[]): T[];
+    /**
+     * Rounds a number to the specified precision
+     * @param value - The number to round
+     * @param precision - The number of decimal places
+     * @returns The rounded number
+     */
+    roundPrecision(value: number, precision: number): number;
+    /**
+     * Generates a random number within the specified range (inclusive)
+     * @param min - The minimum value (default: 0)
+     * @param max - The maximum value (default: 2000)
+     * @returns A random number between min and max, or NaN if inputs are invalid
+     */
     randomRange(min?: number, max?: number): number;
+    /**
+     * Generates a random alphanumeric string of the specified length
+     * @param length - The desired length of the string (default: 12)
+     * @returns A random string containing numbers and letters
+     */
     randomString(length?: number): string;
-    convertHiveAmount(amount: any, fiatSymbol: any, hiveSymbol: any): Promise<any>;
-    jsonParse(str: string): any;
-    getTransaction(client: Client, blockNumber: number, transactionId: any): Promise<SignedTransaction>;
+    /**
+     * Converts a Hive amount from one currency to another using current exchange rates
+     * @param amount - The amount to convert
+     * @param fiatSymbol - The source currency symbol
+     * @param hiveSymbol - The target Hive currency symbol
+     * @returns The converted amount rounded to 3 decimal places
+     */
+    convertHiveAmount(amount: number, fiatSymbol: string, hiveSymbol: string): Promise<number>;
+    /**
+     * Safely parses a JSON string
+     * @param str - The string to parse
+     * @returns The parsed object or null if parsing fails
+     */
+    jsonParse(str: string): any | null;
+    /**
+     * Retrieves a transaction from a specific block
+     * @param client - The Hive client instance
+     * @param blockNumber - The block number containing the transaction
+     * @param transactionId - The transaction ID to retrieve
+     * @returns The signed transaction
+     * @throws Error if transaction is not found in the block
+     */
+    getTransaction(client: Client, blockNumber: number, transactionId: string): Promise<SignedTransaction>;
+    /**
+     * Verifies that a transfer transaction matches the expected parameters
+     * @param transaction - The signed transaction to verify
+     * @param from - Expected sender account
+     * @param to - Expected recipient account
+     * @param amount - Expected transfer amount
+     * @returns True if the transfer matches all parameters
+     */
     verifyTransfer(transaction: SignedTransaction, from: string, to: string, amount: string): Promise<boolean>;
+    /**
+     * Transfers Hive tokens between accounts
+     * @param client - The Hive client instance
+     * @param config - Configuration containing the active key
+     * @param from - Sender account name
+     * @param to - Recipient account name
+     * @param amount - Amount to transfer (will be formatted to 3 decimal places)
+     * @param symbol - Token symbol (e.g., 'HIVE', 'HBD')
+     * @param memo - Optional memo for the transfer
+     * @returns Promise resolving to the broadcast result
+     */
     transferHiveTokens(client: Client, config: Partial<ConfigInterface>, from: string, to: string, amount: string, symbol: string, memo?: string): Promise<import("@hiveio/dhive").TransactionConfirmation>;
+    /**
+     * Broadcasts one or more Hive operations signed by one or multiple private keys.
+     */
+    broadcastOperations(client: Client, operations: Array<[string, any]>, signingKeys: HiveKeyInput | HiveKeyInput[]): Promise<import("@hiveio/dhive").TransactionConfirmation>;
+    /**
+     * Alias for explicitly broadcasting with multiple signatures.
+     */
+    broadcastMultiSigOperations(client: Client, operations: Array<[string, any]>, signingKeys: HiveKeyInput[]): any;
+    /**
+     * Builds a Hive authority object for account_update/account_update2 operations.
+     */
+    createAuthority(keyAuths?: Array<[string, number]>, accountAuths?: Array<[string, number]>, weightThreshold?: number): AuthorityInput;
+    /**
+     * Updates account authorities, enabling native Hive multisig thresholds.
+     */
+    updateAccountAuthorities(client: Client, config: Partial<ConfigInterface>, account: string, authorityUpdate: {
+        owner?: AuthorityInput;
+        active?: AuthorityInput;
+        posting?: AuthorityInput;
+        memo_key?: string;
+        json_metadata?: string;
+        posting_json_metadata?: string;
+        useAccountUpdate2?: boolean;
+    }, signingKeys?: HiveKeyInput | HiveKeyInput[]): Promise<any>;
+    /**
+     * Creates an escrow transfer on Hive.
+     */
+    escrowTransfer(client: Client, config: Partial<ConfigInterface>, options: {
+        from: string;
+        to: string;
+        agent: string;
+        escrow_id: number;
+        hive_amount?: string;
+        hbd_amount?: string;
+        fee: string;
+        ratification_deadline: string | Date;
+        escrow_expiration: string | Date;
+        json_meta?: string | Record<string, any>;
+    }, signingKeys?: HiveKeyInput | HiveKeyInput[]): any;
+    /**
+     * Approves or rejects an escrow transfer.
+     */
+    escrowApprove(client: Client, config: Partial<ConfigInterface>, options: {
+        from: string;
+        to: string;
+        agent: string;
+        who: string;
+        escrow_id: number;
+        approve: boolean;
+    }, signingKeys?: HiveKeyInput | HiveKeyInput[]): any;
+    /**
+     * Opens an escrow dispute.
+     */
+    escrowDispute(client: Client, config: Partial<ConfigInterface>, options: {
+        from: string;
+        to: string;
+        agent: string;
+        who: string;
+        escrow_id: number;
+    }, signingKeys?: HiveKeyInput | HiveKeyInput[]): any;
+    /**
+     * Releases escrow funds.
+     */
+    escrowRelease(client: Client, config: Partial<ConfigInterface>, options: {
+        from: string;
+        to: string;
+        agent: string;
+        who: string;
+        receiver: string;
+        escrow_id: number;
+        hive_amount?: string;
+        hbd_amount?: string;
+    }, signingKeys?: HiveKeyInput | HiveKeyInput[]): any;
+    /**
+     * Transfers Hive tokens to multiple accounts with a delay between transfers
+     * @param client - The Hive client instance
+     * @param config - Configuration containing the active key
+     * @param from - Sender account name
+     * @param accounts - Array of recipient account names
+     * @param amount - Amount to transfer to each account
+     * @param symbol - Token symbol
+     * @param memo - Memo for all transfers
+     * @returns True if all transfers completed successfully
+     */
     transferHiveTokensMultiple(client: Client, config: ConfigInterface, from: string, accounts: string[], amount: string, symbol: string, memo: string): Promise<boolean>;
-    getAccountTransfers(client: Client, account: string, from?: number, max?: number): Promise<any>;
-    getApiJson(client: Client, from?: number, limit?: number): Promise<any>;
+    /**
+     * Retrieves account transfer history
+     * @param client - The Hive client instance
+     * @param account - Account name to get transfers for
+     * @param from - Starting index (default: -1 for most recent)
+     * @param max - Maximum number of transfers to retrieve
+     * @returns Array of transfer operations with date information
+     */
+    getAccountTransfers(client: Client, account: string, from?: number, max?: number): Promise<any[]>;
+    /**
+     * Retrieves custom JSON operations from the hiveapi account
+     * @param client - The Hive client instance
+     * @param from - Starting index (default: -1)
+     * @param limit - Maximum number of operations to retrieve
+     * @returns Array of custom JSON operations with date information
+     */
+    getApiJson(client: Client, from?: number, limit?: number): Promise<any[]>;
+    /**
+     * Transfers Hive Engine tokens between accounts
+     * @param client - The Hive client instance
+     * @param config - Configuration containing the active key and Hive Engine ID
+     * @param from - Sender account name
+     * @param to - Recipient account name
+     * @param quantity - Token quantity to transfer
+     * @param symbol - Token symbol (will be converted to uppercase)
+     * @param memo - Optional memo for the transfer
+     * @returns Promise resolving to the broadcast result
+     */
     transferHiveEngineTokens(client: Client, config: ConfigInterface, from: string, to: string, quantity: string, symbol: string, memo?: string): Promise<import("@hiveio/dhive").TransactionConfirmation>;
+    /**
+     * Transfers Hive Engine tokens to multiple accounts in batches
+     * @param client - The Hive client instance
+     * @param config - Configuration containing the active key and Hive Engine ID
+     * @param from - Sender account name
+     * @param accounts - Array of account objects with 'account' and optional 'amount' properties
+     * @param symbol - Token symbol
+     * @param memo - Memo for all transfers
+     * @param amount - Default amount if not specified per account
+     * @returns Promise that resolves when all batches are completed
+     */
     transferHiveEngineTokensMultiple(client: Client, config: ConfigInterface, from: string, accounts: any[], symbol: string, memo: string, amount?: string): Promise<void>;
+    /**
+     * Issues new Hive Engine tokens to an account
+     * @param client - The Hive client instance
+     * @param config - Configuration containing the active key and Hive Engine ID
+     * @param from - Issuer account name
+     * @param to - Recipient account name
+     * @param symbol - Token symbol
+     * @param quantity - Quantity of tokens to issue
+     * @param memo - Optional memo for the issuance
+     * @returns Promise resolving to the broadcast result
+     */
     issueHiveEngineTokens(client: Client, config: ConfigInterface, from: string, to: string, symbol: string, quantity: string, memo?: string): Promise<import("@hiveio/dhive").TransactionConfirmation>;
+    /**
+     * Issues Hive Engine tokens to multiple accounts in batches
+     * @param client - The Hive client instance
+     * @param config - Configuration containing the active key and Hive Engine ID
+     * @param from - Issuer account name
+     * @param accounts - Array of account objects with 'account' and optional 'amount' properties
+     * @param symbol - Token symbol
+     * @param memo - Memo for all issuances
+     * @param amount - Default amount if not specified per account
+     * @returns Promise that resolves when all batches are completed
+     */
     issueHiveEngineTokensMultiple(client: Client, config: ConfigInterface, from: string, accounts: any[], symbol: string, memo: string, amount?: string): Promise<void>;
-    randomNumber(previousBlockId: any, blockId: any, transactionId: any): number;
+    /**
+     * Schedules a recurrent transfer on Hive.
+     */
+    recurrentTransfer(client: Client, config: Partial<ConfigInterface>, options: {
+        from: string;
+        to: string;
+        amount: string;
+        memo?: string;
+        recurrence: number;
+        executions: number;
+    }, signingKeys?: HiveKeyInput | HiveKeyInput[]): any;
+    /**
+     * Creates a DHF proposal.
+     */
+    createProposal(client: Client, config: Partial<ConfigInterface>, options: {
+        creator: string;
+        receiver: string;
+        start_date: string | Date;
+        end_date: string | Date;
+        daily_pay: string;
+        subject: string;
+        permlink: string;
+    }, signingKeys?: HiveKeyInput | HiveKeyInput[]): any;
+    /**
+     * Votes for/against one or more DHF proposals.
+     */
+    updateProposalVotes(client: Client, config: Partial<ConfigInterface>, options: {
+        voter: string;
+        proposal_ids: number[];
+        approve: boolean;
+    }, signingKeys?: HiveKeyInput | HiveKeyInput[]): any;
+    /**
+     * Removes one or more DHF proposals.
+     */
+    removeProposals(client: Client, config: Partial<ConfigInterface>, options: {
+        proposal_owner: string;
+        proposal_ids: number[];
+    }, signingKeys?: HiveKeyInput | HiveKeyInput[]): any;
+    /**
+     * Generates a deterministic random number based on blockchain data
+     * @param previousBlockId - The previous block ID
+     * @param blockId - The current block ID
+     * @param transactionId - The transaction ID
+     * @returns A deterministic random number between 1 and 100
+     */
+    randomNumber(previousBlockId: string, blockId: string, transactionId: string): number;
+    /**
+     * Upvotes a post or comment
+     * @param client - The Hive client instance
+     * @param config - Configuration containing the posting key
+     * @param voter - The account name doing the voting
+     * @param votePercentage - Vote percentage as a string (default: '100.0')
+     * @param author - The author of the post/comment
+     * @param permlink - The permlink of the post/comment
+     * @returns Promise resolving to the broadcast result
+     * @throws Error if negative voting values are provided
+     */
     upvote(client: Client, config: Partial<ConfigInterface>, voter: string, votePercentage: string, author: string, permlink: string): Promise<import("@hiveio/dhive").TransactionConfirmation>;
+    /**
+     * Downvotes a post or comment
+     * @param client - The Hive client instance
+     * @param config - Configuration containing the posting key
+     * @param voter - The account name doing the voting
+     * @param votePercentage - Vote percentage as a string (default: '100.0')
+     * @param author - The author of the post/comment
+     * @param permlink - The permlink of the post/comment
+     * @returns Promise resolving to the broadcast result
+     */
     downvote(client: Client, config: Partial<ConfigInterface>, voter: string, votePercentage: string, author: string, permlink: string): Promise<import("@hiveio/dhive").TransactionConfirmation>;
+    /**
+     * Converts vote percentage to voting weight for Hive blockchain
+     * @param votePercentage - Vote percentage (0-100)
+     * @returns Voting weight (0-10000)
+     */
     votingWeight(votePercentage: number): number;
-    asyncForEach(array: any[], callback: any): Promise<void>;
+    /**
+     * Executes an async function for each element in an array sequentially
+     * @param array - The array to iterate over
+     * @param callback - The async callback function to execute for each element
+     * @returns Promise that resolves when all iterations are complete
+     */
+    asyncForEach<T>(array: T[], callback: (value: T, index: number, array: T[]) => Promise<void>): Promise<void>;
+    /**
+     * Generates a Hivesigner transfer URL
+     * @param to - Recipient account name
+     * @param memo - Transfer memo
+     * @param amount - Transfer amount with currency symbol
+     * @param redirectUri - URI to redirect to after signing
+     * @returns The complete Hivesigner transfer URL
+     */
     getTransferUrl(to: string, memo: string, amount: string, redirectUri: string): string;
 };
+export {};