@investorphem/stx-utils 1.0.2 → 1.0.3

package/README.md

@@ -5,85 +5,120 @@
 [![License](https://img.shields.io/npm/l/@investorphem/stx-utils.svg?style=flat-square)](LICENSE)
 [![Build Status](https://github.com/investorphem/stx-utils/actions/workflows/publish.yml/badge.svg)](https://github.com/investorphem/stx-utils/actions/workflows/publish.yml)
 [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
-[![Contributors](https://img.shields.io/github/contributors/investorphem/stx-utils.svg)](https://github.com/<your-username>/stx-utils/graphs/contributors)
+[![Contributors](https://img.shields.io/github/contributors/investorphem/stx-utils.svg)](https://github.com/investorphem/stx-utils/graphs/contributors)
 
 ---
 
-## Description
+## 🚀 Description
 
-`@investorphem/stx-utils` is a JavaScript utility library for interacting with the Stacks blockchain. It provides functions to send STX, read contract state, validate addresses, and convert STX units.
+`@investorphem/stx-utils` is a modern JavaScript utility library for interacting with the Stacks blockchain. It provides essential, type-safe functions to send STX programmatically, validate wallet addresses, and cleanly convert STX units for frontend interfaces.
 
-## Features
+## ✨ Features
 
-* Send STX tokens programmatically
-* Read-only contract calls
-* Validate Stacks addresses
-* Convert between STX and micro-STX
-* Check account balances
-* Fully automated GitHub Actions publishing workflow
+* 💸 **Send STX tokens** programmatically via backend or Node.js scripts
+* ✅ **Validate Stacks addresses** securely without crashing your app
+* 🔄 **Convert STX units** between STX and micro-STX with BigInt support
+* 🛡️ **Null-Safe:** Safely handles empty or malformed inputs
+* ⚡ **Modern ESM:** Native ES Module support (`import`/`export`)
+* 🤖 Fully automated GitHub Actions publishing workflow
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @investorphem/stx-utils
-npm install @stacks/transactions @stacks/network @stacks/crypto
 ```
 
-## Usage
+*Note: This package requires `@stacks/network` and `@stacks/transactions` as peer dependencies. Ensure they are installed in your project.*
 
-```js
-const { stxToMicro, microToStx, isValidAddress, sendSTX } = require('@investorphem/stx-utils');
+## 🧠 Usage (ES Modules)
+
+Since version 1.0.2, this package uses standard ES Modules.
+
+```javascript
+import { stxToMicro, microToStx, isValidAddress, sendSTX } from '@investorphem/stx-utils';
 
 console.log(stxToMicro(1.5)); // 1500000n
 console.log(microToStx(1500000n)); // 1.5
-console.log(isValidAddress('ST3J2GVMMM2R07ZFBJDWTYEYAR8FZH5WKDTFJ9AHA')); // true
-
-// Sending STX (async)
-(async () => {
-  const result = await sendSTX('<private-key>', 'ST3J2GVMMM2R07ZFBJDWTYEYAR8FZH5WKDTFJ9AHA', 0.1, 'testnet');
-  console.log(result);
-})();
+console.log(isValidAddress('SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR')); // true
+
+// Sending STX programmatically (async)
+async function executeTransfer() {
+  try {
+    const result = await sendSTX(
+      '<your-private-key>', 
+      'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR', 
+      0.1, 
+      'mainnet' // Defaults to 'testnet' if omitted
+    );
+    console.log("Transaction broadcasted:", result);
+  } catch (error) {
+    console.error("Transfer failed:", error);
+  }
+}
+
+executeTransfer();
 ```
 
-## API
+## 📚 API
 
 ### `stxToMicro(amount)`
 
-Converts STX to micro-STX.
+Converts standard STX to micro-STX (1 STX = 1,000,000 micro-STX).
+
+**Returns:** *BigInt*
+
+---
 
 ### `microToStx(amount)`
 
-Converts micro-STX to STX.
+Converts micro-STX back to standard STX for UI display.
+
+**Returns:** *Number*
+
+---
 
 ### `isValidAddress(address)`
 
-Validates a Stacks address.
+Validates if a string is a properly formatted Stacks address. Safely catches underlying library errors.
+
+**Returns:** *boolean*
+
+---
 
 ### `sendSTX(senderKey, recipient, amount, network)`
 
-Sends STX tokens from a private key to a recipient.
+Broadcasts an STX token transfer to the network using a private key. Designed for Node.js / backend environments.
 
 **Parameters:**
-
-* `senderKey` *(string)* – private key of sender
-* `recipient` *(string)* – STX address of recipient
-* `amount` *(number)* – STX amount
-* `network` *(string)* – 'testnet' or 'mainnet' (default: testnet)
+* `senderKey` *(string)* – Private key of the sender
+* `recipient` *(string)* – STX address of the recipient
+* `amount` *(number)* – STX amount to send (automatically converted to micro-STX)
+* `network` *(string)* – `'testnet'` or `'mainnet'` (default: `'testnet'`)
 
 **Returns:**
+* Promise resolving to the Stacks transaction broadcast result.
+
+---
+
+## ⚙️ Automated Releases
 
-* Promise resolving to transaction result
+This project uses an automated release script. To publish a new version:
 
-## Contributing
+1. Commit your changes: `git commit -m "update stx utilities"`
+2. Run the release command: `npm run release`
 
-Contributions are welcome! Fork the repo, make improvements, and submit a pull request. Ensure code follows [StandardJS style](https://standardjs.com).
+This will automatically bump the patch version, create a git tag, and push to GitHub, triggering the automated NPM publish action.
 
-## License
+---
+
+## 🛠️ Contributing
+
+Contributions are welcome! Please fork the repo, make improvements, and submit a pull request. Ensure code follows [StandardJS style](https://standardjs.com).
+
+## 📄 License
 
 MIT License
 
 ---
 
 *Maintained by Oluwafemi Olagoke*
-
----

package/index.js

@@ -1,33 +1,54 @@
-const { StacksTestnet, StacksMainnet } = require('@stacks/network');
-const { broadcastTransaction, makeSTXTokenTransfer, validateStacksAddress } = require('@stacks/transactions');
+import { StacksTestnet, StacksMainnet } from '@stacks/network';
+import { 
+  broadcastTransaction, 
+  makeSTXTokenTransfer, 
+  validateStacksAddress 
+} from '@stacks/transactions';
 
-function stxToMicro(amount) {
-  return BigInt(Math.round(amount * 1e6));
+// Convert STX to micro-STX (1 STX = 1,000,000 micro-STX)
+export function stxToMicro(amount) {
+  if (amount === undefined || amount === null) return 0n;
+  // Use Math.round to prevent floating-point precision errors before converting to BigInt
+  return BigInt(Math.round(Number(amount) * 1e6));
 }
 
-function microToStx(amount) {
+// Convert micro-STX to STX
+export function microToStx(amount) {
+  if (amount === undefined || amount === null) return 0;
+  // Safely cast to Number (handles both BigInt and string inputs from Stacks API)
   return Number(amount) / 1e6;
 }
 
-function isValidAddress(address) {
-  return validateStacksAddress(address);
+// Validate a Stacks address
+export function isValidAddress(address) {
+  if (!address || typeof address !== 'string') return false;
+  try {
+    return validateStacksAddress(address);
+  } catch {
+    return false; // Prevent app crashes if the library throws on a badly malformed string
+  }
 }
 
-async function sendSTX(senderKey, recipient, amount, network='testnet') {
+// Send STX using a private key (Designed for backend/Node.js usage)
+export async function sendSTX(senderKey, recipient, amount, network = 'testnet') {
+  if (!senderKey || !recipient || !amount) {
+    throw new Error("Missing required parameters (senderKey, recipient, amount) for sendSTX");
+  }
+
   const net = network === 'mainnet' ? new StacksMainnet() : new StacksTestnet();
+
   const txOptions = {
     recipient,
-    amount: stxToMicro(amount),
+    amount: stxToMicro(amount), // Converts STX to micro-STX automatically
     senderKey,
     network: net,
   };
-  const tx = await makeSTXTokenTransfer(txOptions);
-  return await broadcastTransaction(tx, net);
-}
 
-module.exports = {
-  stxToMicro,
-  microToStx,
-  isValidAddress,
-  sendSTX
-};
+  try {
+    const tx = await makeSTXTokenTransfer(txOptions);
+    return await broadcastTransaction(tx, net);
+  } catch (error) {
+    console.error("Failed to broadcast transaction:", error.message);
+    throw error;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@investorphem/stx-utils",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "JavaScript utility library for interacting with the Stacks blockchain.",
   "main": "index.js",
   "type": "module",