hive-stream 3.0.4 → 3.0.5

package/DOCUMENTATION.md

@@ -435,8 +435,700 @@ When the built-in API server is running, the following endpoints are available:
 
 ---
 
+## Social Operations
+
+Follow, unfollow, mute, and reblog users directly from the streamer:
+
+```typescript
+// Direct methods
+await streamer.follow('myaccount', 'targetuser');
+await streamer.unfollow('myaccount', 'targetuser');
+await streamer.mute('myaccount', 'spammer');
+await streamer.reblog('myaccount', 'author', 'great-post');
+
+// Or use builders
+await streamer.ops.follow().follower('myaccount').following('targetuser').send();
+await streamer.ops.unfollow().follower('myaccount').following('targetuser').send();
+await streamer.ops.mute().follower('myaccount').following('spammer').send();
+await streamer.ops.reblog().account('myaccount').author('author').permlink('great-post').send();
+```
+
+---
+
+## Staking Operations
+
+Power up, power down, delegate, and undelegate Hive Power:
+
+```typescript
+// Power up HIVE to HP
+await streamer.powerUp('myaccount', 'myaccount', '100.000');
+await streamer.ops.powerUp().from('myaccount').to('myaccount').amount(100).send();
+
+// Power down (withdraw vesting)
+await streamer.powerDown('myaccount', '50000.000000 VESTS');
+await streamer.ops.powerDown().account('myaccount').vestingShares('50000.000000 VESTS').send();
+
+// Cancel active power down
+await streamer.cancelPowerDown('myaccount');
+await streamer.ops.cancelPowerDown().account('myaccount').send();
+
+// Delegate HP to another account
+await streamer.delegateVestingShares('myaccount', 'recipient', '10000.000000 VESTS');
+await streamer.ops.delegate().delegator('myaccount').delegatee('recipient').vestingShares('10000.000000 VESTS').send();
+
+// Remove delegation
+await streamer.undelegateVestingShares('myaccount', 'recipient');
+await streamer.ops.undelegate().delegator('myaccount').delegatee('recipient').send();
+```
+
+---
+
+## Account Operations
+
+### Claim Rewards
+```typescript
+await streamer.claimRewards('myaccount', '1.000 HIVE', '0.500 HBD', '100.000000 VESTS');
+await streamer.ops.claimRewards()
+    .account('myaccount')
+    .rewardHive('1.000 HIVE')
+    .rewardHbd('0.500 HBD')
+    .rewardVests('100.000000 VESTS')
+    .send();
+```
+
+### Witness Voting
+```typescript
+await streamer.witnessVote('myaccount', 'goodwitness', true);
+await streamer.ops.witnessVote().account('myaccount').witness('goodwitness').approve().send();
+
+// Remove witness vote
+await streamer.witnessVote('myaccount', 'badwitness', false);
+await streamer.ops.witnessVote().account('myaccount').witness('badwitness').unapprove().send();
+```
+
+### Governance Proxy
+```typescript
+await streamer.setProxy('myaccount', 'trustedvoter');
+await streamer.ops.setProxy().account('myaccount').proxy('trustedvoter').send();
+
+// Remove proxy
+await streamer.clearProxy('myaccount');
+await streamer.ops.clearProxy().account('myaccount').send();
+```
+
+### Update Profile
+```typescript
+await streamer.updateProfile('myaccount', {
+    name: 'My Display Name',
+    about: 'Hive developer',
+    location: 'Decentralized',
+    website: 'https://example.com',
+    profile_image: 'https://example.com/avatar.png',
+    cover_image: 'https://example.com/cover.png'
+});
+
+// Or use the builder
+await streamer.ops.updateProfile()
+    .account('myaccount')
+    .name('My Display Name')
+    .about('Hive developer')
+    .website('https://example.com')
+    .profileImage('https://example.com/avatar.png')
+    .set('custom_field', 'custom_value')
+    .send();
+```
+
+### Account Lookup
+```typescript
+const account = await streamer.getAccount('alice');
+const accounts = await streamer.getAccounts(['alice', 'bob', 'charlie']);
+```
+
+---
+
+## Event Subscriptions
+
+In addition to the existing `onTransfer`, `onCustomJson`, `onComment`, `onPost`, and escrow subscriptions, you can now subscribe to:
+
+```typescript
+// Watch all votes on the blockchain
+streamer.onVote((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log(`${data.voter} voted on @${data.author}/${data.permlink} with weight ${data.weight}`);
+});
+
+// Watch delegations
+streamer.onDelegate((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log(`${data.delegator} delegated ${data.vesting_shares} to ${data.delegatee}`);
+});
+
+// Watch power ups
+streamer.onPowerUp((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log(`${data.from} powered up ${data.amount} to ${data.to}`);
+});
+
+// Watch power downs
+streamer.onPowerDown((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log(`${data.account} started power down of ${data.vesting_shares}`);
+});
+
+// Watch reward claims
+streamer.onClaimRewards((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log(`${data.account} claimed rewards`);
+});
+
+// Watch witness votes
+streamer.onAccountWitnessVote((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log(`${data.account} ${data.approve ? 'voted for' : 'unvoted'} witness ${data.witness}`);
+});
+```
+
+---
+
+## Blockchain Helpers
+
+### Reputation Score
+```typescript
+import { Utils } from 'hive-stream';
+
+// Convert raw blockchain reputation to human-readable score (25-75 range)
+const score = Utils.calculateReputation('253948692668213'); // e.g. 73.64
+```
+
+### VESTS / HP Conversion
+```typescript
+// Convert VESTS to Hive Power
+const hp = Utils.vestToHP('1000000', totalVestingFundHive, totalVestingShares); // '500.000'
+
+// Convert HP to VESTS
+const vests = Utils.hpToVest('500', totalVestingFundHive, totalVestingShares); // '1000000.000000'
+
+// Get formatted VESTS string for delegation/power down
+const vestsStr = Utils.hpToVestString('500', totalVestingFundHive, totalVestingShares); // '1000000.000000 VESTS'
+```
+
+### Parse Profile Metadata
+```typescript
+const profile = Utils.parseProfileMetadata(account.posting_json_metadata);
+// { name: 'Alice', about: '...', location: '...', website: '...', profile_image: '...', cover_image: '...' }
+```
+
+---
+
+## Query Namespace
+
+The `streamer.query` namespace provides read-only access to the entire Hive blockchain. No keys required.
+
+### Chain State
+```typescript
+const props = await streamer.query.getDynamicGlobalProperties();
+const chainProps = await streamer.query.getChainProperties();
+const config = await streamer.query.getConfig();
+const price = await streamer.query.getCurrentMedianHistoryPrice();
+const rewardFund = await streamer.query.getRewardFund('post');
+```
+
+### Content & Discussions
+```typescript
+const post = await streamer.query.getContent('author', 'permlink');
+const replies = await streamer.query.getContentReplies('author', 'permlink');
+const votes = await streamer.query.getActiveVotes('author', 'permlink');
+
+const trending = await streamer.query.getTrending({ tag: 'hive', limit: 10 });
+const hot = await streamer.query.getHot({ limit: 20 });
+const newPosts = await streamer.query.getCreated({ tag: 'dev', limit: 10 });
+const blog = await streamer.query.getBlog('alice');
+const feed = await streamer.query.getFeed('alice');
+```
+
+### Social Graph
+```typescript
+const followers = await streamer.query.getFollowers('alice', '', 'blog', 100);
+const following = await streamer.query.getFollowing('alice', '', 'blog', 100);
+const counts = await streamer.query.getFollowCount('alice');
+```
+
+### Delegations & Vesting
+```typescript
+const delegations = await streamer.query.getVestingDelegations('alice');
+```
+
+### Account History
+```typescript
+const history = await streamer.query.getAccountHistory('alice', -1, 100);
+```
+
+### Market & Orders
+```typescript
+const orderBook = await streamer.query.getOrderBook(50);
+const openOrders = await streamer.query.getOpenOrders('alice');
+```
+
+### Resource Credits & Voting Power
+```typescript
+const rc = await streamer.query.getRCMana('alice');
+const vp = await streamer.query.getVPMana('alice');
+const rcAccounts = await streamer.query.findRCAccounts(['alice', 'bob']);
+```
+
+### Communities & Notifications
+```typescript
+const community = await streamer.query.getCommunity('hive-12345');
+const communities = await streamer.query.listCommunities({ limit: 50 });
+const notifications = await streamer.query.getAccountNotifications('alice');
+const subs = await streamer.query.listAllSubscriptions('alice');
+```
+
+### Witnesses
+```typescript
+const witness = await streamer.query.getWitnessByAccount('someguy');
+const topWitnesses = await streamer.query.getWitnessesByVote('', 100);
+```
+
+### Blocks & Transactions
+```typescript
+const block = await streamer.query.getBlock(12345678);
+const header = await streamer.query.getBlockHeader(12345678);
+const ops = await streamer.query.getOperations(12345678);
+const txStatus = await streamer.query.findTransaction('trx-id-here');
+```
+
+### Conversions & Savings
+```typescript
+const conversions = await streamer.query.getConversionRequests('alice');
+const collateralized = await streamer.query.getCollateralizedConversionRequests('alice');
+const savingsWithdrawals = await streamer.query.getSavingsWithdrawFrom('alice');
+```
+
+### Proposals & Account Lookup
+```typescript
+const proposals = await streamer.query.getProposals({ status: 'votable', limit: 50 });
+const accounts = await streamer.query.lookupAccounts('ali', 10);
+```
+
+---
+
+## Savings Operations
+
+```typescript
+// Transfer to savings
+await streamer.transferToSavings('myaccount', 'myaccount', '100', 'HIVE');
+await streamer.ops.transferToSavings().from('myaccount').hive(100).send();
+
+// Transfer from savings (3-day delay)
+await streamer.transferFromSavings('myaccount', 'myaccount', '50', 'HBD', 1);
+await streamer.ops.transferFromSavings().from('myaccount').hbd(50).requestId(1).send();
+
+// Cancel pending savings withdrawal
+await streamer.cancelTransferFromSavings('myaccount', 1);
+```
+
+---
+
+## Convert Operations
+
+```typescript
+// Convert HBD to HIVE (3.5-day delay)
+await streamer.convert('myaccount', '10.000 HBD');
+await streamer.ops.convert().from('myaccount').hbd(10).send();
+
+// Collateralized convert HIVE to HBD (instant, with collateral)
+await streamer.collateralizedConvert('myaccount', '10.000 HIVE');
+await streamer.ops.collateralizedConvert().from('myaccount').hive(10).send();
+```
+
+---
+
+## Market Operations
+
+```typescript
+// Create a limit order (sell HIVE for HBD)
+await streamer.ops.limitOrder()
+    .owner('myaccount')
+    .amountToSell('10.000 HIVE')
+    .minToReceive('4.000 HBD')
+    .expiration(new Date(Date.now() + 7 * 24 * 60 * 60 * 1000))
+    .send();
+
+// Cancel an order
+await streamer.ops.cancelOrder().owner('myaccount').orderId(12345).send();
+```
+
+---
+
+## Content Operations
+
+```typescript
+// Delete a post or comment
+await streamer.deleteComment('myaccount', 'my-permlink');
+await streamer.ops.deleteComment().author('myaccount').permlink('my-permlink').send();
+
+// Set post options with beneficiaries
+await streamer.ops.commentOptions()
+    .author('myaccount')
+    .permlink('my-post')
+    .maxAcceptedPayout('1000.000 HBD')
+    .percentHbd(5000)
+    .beneficiary('devfund', 500)
+    .beneficiary('curator', 1000)
+    .send();
+```
+
+---
+
+## Vesting Withdrawal Routes
+
+```typescript
+// Route 50% of power-down to another account
+await streamer.ops.withdrawRoute()
+    .from('myaccount')
+    .to('savings-account')
+    .percent(5000)
+    .autoVest(true) // Auto power-up at destination
+    .send();
+```
+
+---
+
+## Witness Operations
+
+```typescript
+// Publish price feed (witnesses only)
+await streamer.feedPublish('mywitness', '0.400 HBD', '1.000 HIVE');
+```
+
+---
+
+## Additional Event Subscriptions
+
+```typescript
+// Watch follows/unfollows/mutes
+streamer.onFollow((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log(`${data.follower} ${data.what.length ? 'followed' : 'unfollowed'} ${data.following}`);
+});
+
+// Watch reblogs
+streamer.onReblog((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log(`${data.account} reblogged @${data.author}/${data.permlink}`);
+});
+
+// Watch account updates
+streamer.onAccountUpdate((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log(`${data.account} updated their account`);
+});
+
+// Watch comment deletions
+streamer.onDeleteComment((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log(`${data.author} deleted ${data.permlink}`);
+});
+
+// Watch market activity
+streamer.onLimitOrder((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log('Market order activity:', data);
+});
+
+// Watch savings transfers
+streamer.onSavingsTransfer((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log('Savings transfer:', data);
+});
+
+// Watch HBD/HIVE conversions
+streamer.onConvert((data, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+    console.log('Conversion:', data);
+});
+```
+
+---
+
+## Content Helpers
+
+```typescript
+import { Utils } from 'hive-stream';
+
+// Generate a permlink from a title
+const permlink = Utils.generatePermlink('My Awesome Post!'); // 'my-awesome-post'
+
+// Generate a reply permlink
+const replyPermlink = Utils.generateReplyPermlink('parent-post'); // 're-parent-post-20260318...'
+
+// Create post metadata JSON
+const metadata = Utils.createPostMetadata({
+    tags: ['hive', 'development'],
+    image: ['https://example.com/hero.png'],
+    description: 'A great post about Hive development',
+    app: 'my-app/1.0'
+});
+```
+
+---
+
+## Account Validation
+
+```typescript
+// Validate account name format
+const error = Utils.validateAccountName('alice'); // null (valid)
+const error2 = Utils.validateAccountName('AB'); // 'Account name must be at least 3 characters'
+
+// Quick boolean check
+const valid = Utils.isValidAccountName('alice'); // true
+
+// Check if account exists on chain
+const exists = await Utils.accountExists(client, 'alice'); // true/false
+```
+
+---
+
+## URL & Link Parsing
+
+```typescript
+// Parse Hive URLs
+Utils.parseHiveUrl('@alice/my-post');
+// { author: 'alice', permlink: 'my-post' }
+
+Utils.parseHiveUrl('https://hive.blog/hive-12345/@alice/my-post');
+// { author: 'alice', permlink: 'my-post', category: 'hive-12345' }
+```
+
+---
+
+## Voting Power & Vote Value
+
+```typescript
+// Calculate current voting mana %
+const mana = Utils.calculateVotingMana(account); // 98.5
+
+// Get effective vesting shares (own + received - delegated)
+const effectiveVests = Utils.getEffectiveVestingShares(account);
+
+// Estimate vote value in USD
+const voteValue = Utils.estimateVoteValue(
+    mana,           // current voting mana %
+    100,            // vote weight %
+    effectiveVests, // effective vesting shares
+    rewardFund,     // from query.getRewardFund()
+    medianPrice     // from query.getCurrentMedianHistoryPrice()
+);
+```
+
+---
+
+## Memo Encryption
+
+```typescript
+// Encode a private memo
+const encoded = Utils.encodeMemo(privateMemoKey, receiverPublicMemoKey, 'secret message');
+
+// Decode a private memo
+const decoded = Utils.decodeMemo(privateMemoKey, encodedMemo);
+```
+
+---
+
+## Post Builder
+
+The post builder is the easiest way to create posts and replies on Hive. It atomically combines `comment` + `comment_options` in a single transaction, handling beneficiaries, metadata, communities, and more.
+
+```typescript
+// Create a post with beneficiaries
+await streamer.ops.post()
+    .author('alice')
+    .title('My First dApp Post')
+    .body('Hello from hive-stream!')
+    .tags('hive', 'dev', 'tutorial')
+    .community('hive-169321')
+    .beneficiary('devfund', 500)     // 5%
+    .beneficiary('alice-savings', 1000)  // 10%
+    .maxAcceptedPayout(100, 'HBD')
+    .percentHbd(5000)                // 50% HBD
+    .app('my-app/1.0')
+    .image('https://example.com/hero.png')
+    .description('A tutorial on building dApps')
+    .metadata('canonical_url', 'https://myapp.com/posts/1')
+    .send();
+
+// Reply to a post
+await streamer.ops.post()
+    .author('bob')
+    .parentAuthor('alice')
+    .parentPermlink('my-first-dapp-post')
+    .body('Great post! Very helpful.')
+    .send();
+
+// Post with zero payout (decline rewards)
+await streamer.ops.post()
+    .author('alice')
+    .title('PSA: Important Announcement')
+    .body('This is a community announcement.')
+    .tags('psa')
+    .maxAcceptedPayout(0, 'HBD')
+    .send();
+```
+
+---
+
+## Batch Operations
+
+Batch multiple operations into a single atomic transaction:
+
+```typescript
+// Vote + comment in one transaction
+await streamer.batch()
+    .vote('alice', 'bob', 'great-post', 10000)
+    .comment('alice', 're-great-post-reply', 'bob', 'great-post', '', 'Love this!', '{}')
+    .send();
+
+// Multiple transfers in one transaction
+await streamer.batch()
+    .transfer('alice', 'bob', '1.000 HIVE', 'payment 1')
+    .transfer('alice', 'carol', '2.000 HIVE', 'payment 2')
+    .transfer('alice', 'dave', '3.000 HIVE', 'payment 3')
+    .send();
+
+// Mix different operation types
+await streamer.batch()
+    .add(['transfer', { from: 'alice', to: 'bob', amount: '1.000 HIVE', memo: '' }])
+    .customJson('myapp', { action: 'register' }, 'alice')
+    .send();
+```
+
+---
+
+## Authority Management
+
+Manage posting authority for Hive apps:
+
+```typescript
+// Check if an app has posting authority
+const hasAuth = await streamer.hasPostingAuth('alice', 'myapp');
+
+// Grant posting authority to an app
+await streamer.grantPostingAuth('alice', 'myapp');
+
+// Revoke posting authority
+await streamer.revokePostingAuth('alice', 'myapp');
+```
+
+---
+
+## Power Down Schedule
+
+Calculate when power down payments arrive:
+
+```typescript
+const schedule = Utils.calculatePowerDownSchedule(account);
+// [
+//   { week: 1, date: 2026-03-25T..., amount: '1000.000000', vestingShares: '1000.000000 VESTS' },
+//   { week: 2, date: 2026-04-01T..., amount: '1000.000000', vestingShares: '1000.000000 VESTS' },
+//   ...up to 13 weeks
+// ]
+```
+
+---
+
+## HBD Savings Interest
+
+```typescript
+const interest = Utils.calculateHbdInterest(
+    account.savings_hbd_balance,  // '1000.000 HBD'
+    account.savings_hbd_last_interest_payment,
+    15  // current APR %
+);
+// '12.328' (pending interest in HBD)
+```
+
+---
+
+## Payout Helpers
+
+```typescript
+// Is the post still earning?
+Utils.isInPayoutWindow(post);  // true/false
+
+// How long until payout?
+Utils.timeUntilPayout(post);  // milliseconds (0 if already paid)
+
+// What's the payout value?
+Utils.getPendingPayout(post);  // '10.500' (HBD)
+```
+
+---
+
+## Account Value Calculator
+
+```typescript
+const value = Utils.calculateAccountValue(
+    account,
+    hivePrice,           // e.g. 0.40 USD
+    hbdPrice,            // e.g. 1.00 USD
+    totalVestingFundHive,
+    totalVestingShares
+);
+// {
+//   hive: 100,           // liquid HIVE
+//   hbd: 50,             // liquid HBD
+//   savings_hive: 200,   // savings HIVE
+//   savings_hbd: 100,    // savings HBD
+//   hp: 500,             // Hive Power (HP)
+//   total_hive: 800,     // total in HIVE terms
+//   total_usd: 470.0     // total in USD
+// }
+```
+
+---
+
+## Content Extraction
+
+```typescript
+// Extract all images from a post body (for thumbnails, galleries)
+const images = Utils.extractImagesFromBody(post.body);
+// ['https://example.com/img1.png', 'https://example.com/img2.jpg']
+
+// Extract all hyperlinks (excluding images)
+const links = Utils.extractLinksFromBody(post.body);
+
+// Generate a plain-text summary (for previews, SEO)
+const summary = Utils.generatePostSummary(post.body, 200);
+// 'Hello world. This is a great post about...'
+```
+
+---
+
+## Hivesigner URLs
+
+```typescript
+// Generate signing URLs for any operation
+const transferUrl = Utils.getTransferUrl('bob', 'thanks', '1.000 HIVE', 'https://myapp.com');
+const voteUrl = Utils.getVoteUrl('alice', 'bob', 'great-post', 10000);
+const delegateUrl = Utils.getDelegateUrl('alice', 'bob', '1000.000000 VESTS');
+const followUrl = Utils.getFollowUrl('alice', 'bob');
+
+// Generic signing URL for any operation type
+const url = Utils.getHivesignerSignUrl('transfer', {
+    from: 'alice', to: 'bob', amount: '1.000 HIVE'
+}, 'https://myapp.com/callback');
+```
+
+---
+
+## Transfer Memo Helpers
+
+```typescript
+// Check if a memo is encrypted
+Utils.isEncryptedMemo('#encrypted-content');  // true
+Utils.isEncryptedMemo('regular memo');        // false
+
+// Create structured JSON memos (for exchanges, apps)
+const memo = Utils.createJsonMemo({ action: 'deposit', orderId: 12345 });
+
+// Parse JSON memos from transfers
+const data = Utils.parseJsonMemo('{"action":"deposit","orderId":12345}');
+// { action: 'deposit', orderId: 12345 }
+Utils.parseJsonMemo('regular memo');  // null
+```
+
+---
+
 ## Utilities
-The library includes helpers for JSON parsing, randomness, and transfer verification. See `src/utils.ts` for details.
+The library includes additional helpers for JSON parsing, randomness, seeded RNG, and transfer verification. See `src/utils.ts` for the complete API.
 
 ---