hive-stream 3.0.3 → 3.0.4

package/README.md

@@ -54,6 +54,7 @@ CamelCase config keys are recommended for readability. Legacy uppercase keys are
 
 ```
 const options = {
+  env: true,
   activeKey: '',
   postingKey: '',
   jsonId: 'hivestream',
@@ -77,6 +78,8 @@ const options = {
 const ss = new Streamer(options);
 ```
 
+If you prefer loading credentials from environment variables, pass `env: true`. Hive Stream will read canonical keys like `ACTIVE_KEY` and `USERNAME`, plus Hive-friendly aliases like `HIVE_ACCOUNT` and `HIVE_ACTIVE_KEY`.
+
 If you want the built-in API without starting block streaming yet:
 
 ```javascript
@@ -102,8 +105,9 @@ These event subscriptions and contract actions are separate paths: subscriptions
 #### Watch for transfers
 
 ```javascript
-ss.onTransfer('myaccount', (op, { sender, amount, asset, memo }, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+ss.onTransfer('myaccount', (op, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
   // Fires only when op.to === 'myaccount'
+  // Parse op.amount yourself, for example: "1.000 HIVE"
 });
 ```
 
@@ -180,6 +184,20 @@ transferHiveTokens(from, to, amount, symbol, memo = '') {
 }
 ```
 
+### Burn Hive (HIVE or HBD)
+```javascript
+burnHiveTokens(from, amount, symbol, memo = '') {
+
+}
+```
+
+### Burn A Percentage Of An Incoming Transfer
+```javascript
+burnTransferPercentage(from, transferOrAmount, percentage, memo = '', allowedSymbols = ['HIVE', 'HBD']) {
+
+}
+```
+
 ### Transfer Hive Engine Tokens
 ```javascript
 transferHiveEngineTokens(from, to, symbol, quantity, memo = '') {
@@ -187,6 +205,13 @@ transferHiveEngineTokens(from, to, symbol, quantity, memo = '') {
 }
 ```
 
+### Burn Hive Engine Tokens
+```javascript
+burnHiveEngineTokens(from, symbol, quantity, memo = '') {
+
+}
+```
+
 ### Transfer Hive Engine Tokens to Multiple Accounts
 ```javascript
 transferHiveEngineTokensMultiple(from, accounts = [], symbol, memo = '', amount = '0') {
@@ -194,6 +219,150 @@ transferHiveEngineTokensMultiple(from, accounts = [], symbol, memo = '', amount
 }
 ```
 
+### Burn part of an inbound transfer safely
+```javascript
+const { Streamer } = require('hive-stream');
+
+const ss = new Streamer({ env: true });
+
+ss.flows.autoBurnIncomingTransfers({
+  percentage: 67,
+  memo: ({ transaction }) => `Auto-burn 67% of ${transaction.id}`
+});
+
+ss.start();
+```
+
+### Forward inbound transfers automatically
+```javascript
+const { Streamer } = require('hive-stream');
+
+const ss = new Streamer({ env: true });
+
+ss.flows.autoForwardIncomingTransfers({
+  to: 'treasury',
+  percentage: 100,
+  memo: ({ transaction }) => `Forwarded from ${transaction.id}`
+});
+
+ss.start();
+```
+
+### Split inbound transfers across multiple accounts
+```javascript
+const { Streamer } = require('hive-stream');
+
+const ss = new Streamer({ env: true });
+
+ss.flows.autoSplitIncomingTransfers({
+  recipients: [
+    { account: 'null', percentage: 69, memo: 'Feel the burn' },
+    { account: 'treasury' }
+  ]
+});
+
+ss.start();
+```
+
+### Refund inbound transfers automatically
+```javascript
+const { Streamer } = require('hive-stream');
+
+const ss = new Streamer({ env: true });
+
+ss.flows.autoRefundIncomingTransfers({
+  memo: ({ transfer }) => `Refunded ${transfer.rawAmount} to ${transfer.from}`
+});
+
+ss.start();
+```
+
+### Route inbound transfers with one flow
+```javascript
+const { Streamer } = require('hive-stream');
+
+const ss = new Streamer({ env: true });
+
+ss.flows.autoRouteIncomingTransfers({
+  routes: [
+    { type: 'burn', percentage: 67, memo: 'Auto-burn 67%' },
+    { to: 'treasury', memo: 'Treasury remainder' }
+  ]
+});
+
+ss.start();
+```
+
+### Route grouped payouts with an optional on-top donation
+```javascript
+const { Streamer } = require('hive-stream');
+
+const ss = new Streamer({ env: true });
+
+ss.flows.autoRouteIncomingTransfers({
+  account: 'tweet-backup',
+  routes: [
+    { to: 'tweet-catcher', percentage: 20, memo: 'Tweet watcher share' },
+    { group: [{ account: 'node-1' }, { account: 'node-2' }], percentage: 4, memo: 'Node operator share' },
+    { group: [{ account: 'wit-1' }, { account: 'wit-2' }], percentage: 6, memo: 'Witness share' },
+    { type: 'burn', percentage: 70, memo: 'Burn share' },
+    { to: 'platform-op', mode: 'onTop', percentage: 8, memo: 'Optional platform donation' }
+  ]
+});
+
+ss.start();
+```
+
+### Chain inbound transfer flows with a builder
+```javascript
+const { Streamer } = require('hive-stream');
+
+const ss = new Streamer({ env: true });
+
+ss.flows
+  .incomingTransfers()
+  .burn(69, 'Feel the burn')
+  .remainderTo('treasury', 'Treasury remainder')
+  .start();
+
+ss.start();
+```
+
+### Preview a payout plan before the flow starts
+```javascript
+const { Streamer } = require('hive-stream');
+
+const ss = new Streamer({ env: true });
+
+const plan = ss.flows
+  .incomingTransfers('tweet-backup')
+  .forwardTo('tweet-catcher', 20, 'Tweet watcher share')
+  .forwardGroup([{ account: 'node-1' }, { account: 'node-2' }], 4, { memo: 'Node operator share' })
+  .remainderToGroup([{ account: 'wit-1' }, { account: 'wit-2' }], { memo: 'Witness share' })
+  .burn(70, 'Burn share')
+  .donateOnTop('platform-op', 8, 'Optional platform donation')
+  .plan({ from: 'buyer', to: 'tweet-backup', amount: '1.080 HBD', memo: 'Archive this tweet' });
+
+console.log(plan.baseAmount);  // "1.000"
+console.log(plan.onTopAmount); // "0.080"
+console.log(plan.routes);
+```
+
+`flows.autoBurnIncomingTransfers()` is the quickest high-level option for the burn case. `flows.autoForwardIncomingTransfers()` covers treasury forwarding, `flows.autoSplitIncomingTransfers()` handles common revenue-sharing, and `flows.autoRefundIncomingTransfers()` is useful for rejecting unsupported payments. `flows.autoRouteIncomingTransfers()` is the general router for mixed burn/transfer/group routes, and `flows.planIncomingTransferRoutes()` previews the same math without broadcasting. In base routes, one destination can omit `percentage`/`basisPoints` and automatically receive the remainder. Routes with `mode: 'onTop'` are treated as a surcharge on the base payout amount, so a `1.000 HBD` base payout with an `8%` donation should arrive as `1.080 HBD`.
+
+`flows.incomingTransfers()` is the chainable version of the same idea. Single-step builders compile down to `autoBurnIncomingTransfers()`, `autoForwardIncomingTransfers()`, or `autoRefundIncomingTransfers()`. Multi-step builders compile down to `autoRouteIncomingTransfers()`, and `.plan(...)` gives you the exact rounded output before any transfer is sent.
+
+### Money Namespace
+```javascript
+const ss = new Streamer();
+
+ss.money.parseAssetAmount('1.000 HIVE');
+ss.money.formatAmount('1.2399'); // "1.239"
+ss.money.calculatePercentageAmount('10.000', 12.5); // "1.250"
+ss.money.splitAmountByBasisPoints('1.000', [6900, 3100]); // ["0.690", "0.310"]
+ss.money.splitAmountByWeights('1.080', [10000, 800]); // ["1.000", "0.080"]
+```
+
 ### Issue Hive Engine Tokens
 ```javascript
 issueHiveEngineTokens(from, to, symbol, quantity, memo = '') {
@@ -244,6 +413,59 @@ updateProposalVotes({ voter, proposal_ids, approve }, signingKeys?)
 removeProposals({ proposal_owner, proposal_ids }, signingKeys?)
 ```
 
+### Operation Builders
+```javascript
+const { Streamer } = require('hive-stream');
+
+const ss = new Streamer({ env: true });
+
+await ss.ops
+  .transfer()
+  .from('alice')
+  .to('bob')
+  .hive(1.25)
+  .memo('Builder transfer example')
+  .send();
+
+await ss.ops
+  .createProposal()
+  .creator('alice')
+  .receiver('treasury')
+  .startDate(new Date('2026-04-01T00:00:00.000Z'))
+  .endDate(new Date('2026-05-01T00:00:00.000Z'))
+  .dailyHbd(12.5)
+  .subject('Builder proposal example')
+  .permlink('builder-proposal-example')
+  .send();
+```
+
+Additional chainable write builders are available for Hive Engine token ops and governance/voting:
+
+```javascript
+await ss.ops
+  .transferEngine()
+  .from('alice')
+  .to('bob')
+  .symbol('BEE')
+  .quantity('1.23456')
+  .memo('Engine transfer')
+  .send();
+
+await ss.ops
+  .voteProposals()
+  .voter('alice')
+  .ids(1, 2, 3)
+  .approve()
+  .send();
+
+await ss.ops
+  .upvote()
+  .author('bob')
+  .permlink('my-post')
+  .weight(25)
+  .send();
+```
+
 ### Upvote/Downvote Posts
 ```javascript
 upvote(votePercentage = '100.0', username, permlink) {
@@ -374,6 +596,21 @@ Sample snippets for the newest contracts live in `examples/contracts/`:
 - `examples/contracts/tipjar.ts`
 - `examples/contracts/exchange.ts`
 
+Higher-level flow examples live in `examples/flows/`:
+
+- `examples/flows/auto-burn.ts`
+- `examples/flows/auto-forward.ts`
+- `examples/flows/auto-split.ts`
+- `examples/flows/auto-refund.ts`
+- `examples/flows/builder-burn-route.ts`
+- `examples/flows/grouped-route-on-top.ts`
+- `examples/flows/builder-payout-plan.ts`
+
+Chainable operation examples live in `examples/ops/`:
+
+- `examples/ops/transfer-builder.ts`
+- `examples/ops/proposal-builder.ts`
+
 ## Time-based Actions
 
 It's like a cron job for your contracts. Time-based actions allow you to execute contract functions over a wide variety of different periods. Want to call a function every 3 seconds block time or want to call a function once per day? Time-based actions are an easy way to run time code.

package/dist/builders.d.ts

@@ -0,0 +1,176 @@
+import type { Streamer } from './streamer';
+import type { BurnOperationBuilder, EscrowTransferBuilder, FlowAllocationInput, FlowDedupeStore, FlowGroupRecipient, FlowGroupSplitStrategy, FlowMemoInput, FlowSubscriptionHandle, HiveEngineBurnBuilder, HiveEngineIssueBuilder, HiveEngineTransferBuilder, IncomingTransferFlowBuilder, PlannedIncomingTransferRoutes, ProposalBuilder, ProposalVotesBuilder, RemoveProposalsBuilder, RecurrentTransferBuilder, TransferEvent, TransferOperationBuilder, VoteBuilder } from './types/hive-stream';
+export declare class IncomingTransfersBuilder implements IncomingTransferFlowBuilder {
+    private readonly streamer;
+    private account?;
+    private allowedSymbols?;
+    private dedupeStore?;
+    private ignoreZeroAmountValue?;
+    private errorHandler?;
+    private defaultMemo?;
+    private steps;
+    constructor(streamer: Streamer, account?: string);
+    forAccount(account: string): this;
+    allowSymbols(...symbols: string[]): this;
+    memo(memo: FlowMemoInput): this;
+    dedupeWith(store: FlowDedupeStore): this;
+    ignoreZeroAmount(ignore?: boolean): this;
+    onError(handler: (error: unknown, event: TransferEvent) => void | Promise<void>): this;
+    burn(allocation: FlowAllocationInput, memo?: FlowMemoInput): this;
+    burnOnTop(allocation: FlowAllocationInput, memo?: FlowMemoInput): this;
+    forwardTo(to: string, allocation?: FlowAllocationInput, memo?: FlowMemoInput): this;
+    forwardOnTop(to: string, allocation: FlowAllocationInput, memo?: FlowMemoInput): this;
+    donateOnTop(to: string, allocation: FlowAllocationInput, memo?: FlowMemoInput): this;
+    forwardGroup(recipients: FlowGroupRecipient[], allocation: FlowAllocationInput, options?: {
+        memo?: FlowMemoInput;
+        split?: FlowGroupSplitStrategy;
+    }): this;
+    forwardGroupOnTop(recipients: FlowGroupRecipient[], allocation: FlowAllocationInput, options?: {
+        memo?: FlowMemoInput;
+        split?: FlowGroupSplitStrategy;
+    }): this;
+    remainderTo(to: string, memo?: FlowMemoInput): this;
+    remainderToGroup(recipients: FlowGroupRecipient[], options?: {
+        memo?: FlowMemoInput;
+        split?: FlowGroupSplitStrategy;
+    }): this;
+    refund(memo?: FlowMemoInput): this;
+    refundPortion(allocation: FlowAllocationInput, memo?: FlowMemoInput): this;
+    remainderToSender(memo?: FlowMemoInput): this;
+    plan(transfer: string | TransferEvent | {
+        amount?: string;
+        from?: string;
+        to?: string;
+        memo?: string;
+    }): PlannedIncomingTransferRoutes;
+    start(): FlowSubscriptionHandle;
+    private buildRoutes;
+}
+export declare class HiveTransferBuilder implements TransferOperationBuilder {
+    private readonly streamer;
+    private state;
+    constructor(streamer: Streamer);
+    from(account: string): this;
+    to(account: string): this;
+    amount(amount: string | number, symbol?: string): this;
+    hive(amount: string | number): this;
+    hbd(amount: string | number): this;
+    memo(memo: string): this;
+    send(): any;
+}
+export declare class HiveBurnBuilder implements BurnOperationBuilder {
+    private readonly streamer;
+    private state;
+    constructor(streamer: Streamer);
+    from(account: string): this;
+    amount(amount: string | number, symbol?: string): this;
+    hive(amount: string | number): this;
+    hbd(amount: string | number): this;
+    memo(memo: string): this;
+    send(): any;
+}
+export declare class HiveEscrowTransferBuilder implements EscrowTransferBuilder {
+    private readonly streamer;
+    private state;
+    constructor(streamer: Streamer);
+    from(account: string): this;
+    to(account: string): this;
+    agent(account: string): this;
+    id(escrowId: number): this;
+    hive(amount: string | number): this;
+    hbd(amount: string | number): this;
+    fee(amount: string | number, symbol?: string): this;
+    ratificationDeadline(value: string | Date): this;
+    expiration(value: string | Date): this;
+    jsonMeta(meta: string | Record<string, any>): this;
+    send(signingKeys?: string | string[]): any;
+}
+export declare class HiveRecurrentTransferBuilder implements RecurrentTransferBuilder {
+    private readonly streamer;
+    private state;
+    constructor(streamer: Streamer);
+    from(account: string): this;
+    to(account: string): this;
+    amount(amount: string | number, symbol?: string): this;
+    hive(amount: string | number): this;
+    hbd(amount: string | number): this;
+    memo(memo: string): this;
+    recurrence(value: number): this;
+    executions(value: number): this;
+    send(signingKeys?: string | string[]): any;
+}
+export declare class HiveProposalBuilder implements ProposalBuilder {
+    private readonly streamer;
+    private state;
+    constructor(streamer: Streamer);
+    creator(account: string): this;
+    receiver(account: string): this;
+    startDate(value: string | Date): this;
+    endDate(value: string | Date): this;
+    dailyPay(amount: string | number, symbol?: string): this;
+    dailyHive(amount: string | number): this;
+    dailyHbd(amount: string | number): this;
+    subject(value: string): this;
+    permlink(value: string): this;
+    send(signingKeys?: string | string[]): any;
+}
+export declare class HiveEngineTokenTransferBuilder implements HiveEngineTransferBuilder {
+    private readonly streamer;
+    private state;
+    constructor(streamer: Streamer);
+    from(account: string): this;
+    to(account: string): this;
+    symbol(symbol: string): this;
+    quantity(quantity: string | number): this;
+    memo(memo: string): this;
+    send(): any;
+}
+export declare class HiveEngineTokenBurnBuilder implements HiveEngineBurnBuilder {
+    private readonly streamer;
+    private state;
+    constructor(streamer: Streamer);
+    from(account: string): this;
+    symbol(symbol: string): this;
+    quantity(quantity: string | number): this;
+    memo(memo: string): this;
+    send(): any;
+}
+export declare class HiveEngineTokenIssueBuilder implements HiveEngineIssueBuilder {
+    private readonly streamer;
+    private state;
+    constructor(streamer: Streamer);
+    from(account: string): this;
+    to(account: string): this;
+    symbol(symbol: string): this;
+    quantity(quantity: string | number): this;
+    memo(memo: string): this;
+    send(): any;
+}
+export declare class HiveProposalVotesBuilder implements ProposalVotesBuilder {
+    private readonly streamer;
+    private state;
+    constructor(streamer: Streamer);
+    voter(account: string): this;
+    ids(...proposalIds: number[]): this;
+    approve(value?: boolean): this;
+    reject(): this;
+    send(signingKeys?: string | string[]): any;
+}
+export declare class HiveRemoveProposalsBuilder implements RemoveProposalsBuilder {
+    private readonly streamer;
+    private state;
+    constructor(streamer: Streamer);
+    owner(account: string): this;
+    ids(...proposalIds: number[]): this;
+    send(signingKeys?: string | string[]): any;
+}
+export declare class HiveVoteBuilder implements VoteBuilder {
+    private readonly streamer;
+    private readonly direction;
+    private state;
+    constructor(streamer: Streamer, direction: 'upvote' | 'downvote');
+    author(account: string): this;
+    permlink(value: string): this;
+    weight(value: string | number): this;
+    send(): any;
+}