txo_parser 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 sandy-mount
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# TXO URI Parser
+
+A pure JavaScript ES module for parsing and formatting TXO URIs according to the [TXO URI Specification v0.1](txo_uri.md).
+
+## Installation
+
+```bash
+npm install txo_parser
+```
+
+For global installation (to use the CLI):
+
+```bash
+npm install -g txo_parser
+```
+
+## Usage
+
+### As a Module
+
+```javascript
+import { parseTxoUri, isValidTxoUri, formatTxoUri } from 'txo_parser'
+
+// Parse a TXO URI
+const uri =
+  'txo:btc:4e9c1ef9ba5fa3b0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0:0?amount=0.75'
+const parsed = parseTxoUri(uri)
+console.log(parsed)
+// Output:
+// {
+//   network: 'btc',
+//   txid: '4e9c1ef9ba5fa3b0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0',
+//   output: 0,
+//   amount: 0.75
+// }
+
+// Check if a URI is valid
+console.log(isValidTxoUri(uri)) // true
+
+// Format a JSON object into a TXO URI
+const data = {
+  network: 'btc',
+  txid: '4e9c1ef9ba5fa3b0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0',
+  output: 0,
+  amount: 0.75,
+  script_type: 'p2tr'
+}
+const formattedUri = formatTxoUri(data)
+console.log(formattedUri)
+// Output: txo:btc:4e9c1ef9ba5fa3b0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0:0?amount=0.75&script_type=p2tr
+```
+
+### Using the CLI
+
+The package includes a command-line tool that allows you to parse TXO URIs directly from the terminal:
+
+```bash
+# Parse a TXO URI and output the full JSON
+txo-parser "txo:btc:4e9c1ef9ba5fa3b0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0:0?amount=0.75"
+
+# Extract just the txid
+txo-parser "txo:btc:4e9c1ef9ba5fa3b0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0:0" --txid
+
+# Extract the network
+txo-parser "txo:btc:4e9c1ef9ba5fa3b0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0:0" --network
+
+# Get help
+txo-parser --help
+```
+
+If you haven't installed the package globally, you can use `npx`:
+
+```bash
+npx txo-parser "txo:btc:4e9c1ef9ba5fa3b0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0:0"
+```
+
+## API
+
+### `parseTxoUri(uri)`
+
+Parses a TXO URI string and returns a JSON object.
+
+- **Parameters:**
+  - `uri` (string): The TXO URI to parse
+- **Returns:** Object with parsed components
+- **Throws:** Error if URI format is invalid
+
+### `isValidTxoUri(uri)`
+
+Checks if a string is a valid TXO URI.
+
+- **Parameters:**
+  - `uri` (string): The URI to validate
+- **Returns:** Boolean indicating validity
+
+### `formatTxoUri(data)`
+
+Formats a JSON object into a TXO URI string.
+
+- **Parameters:**
+  - `data` (object): The data to format (must include network, txid, and output)
+- **Returns:** Formatted TXO URI string
+- **Throws:** Error if required fields are missing or invalid
+
+## Testing
+
+Run tests with:
+
+```bash
+npm test
+```
+
+## Using in Node.js Projects
+
+If you're using this in a Node.js project, make sure your package.json includes:
+
+```json
+{
+  "type": "module"
+}
+```
+
+Or when importing in a CommonJS project:
+
+```javascript
+import { parseTxoUri } from 'txo_parser/index.js'
+```
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+/**
+ * TXO URI Parser CLI
+ * 
+ * A command-line interface for the TXO URI parser
+ * Usage: txo-parser <uri> [options]
+ * 
+ * Options:
+ *   --<field>    Output only the specified field (e.g., --txid, --network, --output)
+ *   --help       Show help
+ */
+
+import { parseTxoUri, isValidTxoUri } from './index.js';
+
+const args = process.argv.slice(2);
+
+// Help message
+function showHelp () {
+  console.log(`
+TXO URI Parser CLI
+
+Parse TXO URIs from the command line and output JSON or specific fields.
+
+Usage: 
+  txo-parser <uri> [options]
+
+Options:
+  --<field>    Output only the specified field (e.g., --txid, --network, --output)
+  --help       Show this help message
+
+Examples:
+  txo-parser "txo:btc:4e9c1ef9ba5fa3b0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabb:0"
+  txo-parser "txo:btc:4e9c1ef9ba5fa3b0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabb:0?amount=0.75" --txid
+  txo-parser "txo:btc:4e9c1ef9ba5fa3b0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabb:0" --network
+  `);
+}
+
+// Check for help
+if (args.includes('--help') || args.length === 0) {
+  showHelp();
+  process.exit(0);
+}
+
+// Get the URI and options
+const uri = args[0];
+const options = args.slice(1);
+
+try {
+  // Parse the URI
+  if (!isValidTxoUri(uri)) {
+    console.error('Error: Invalid TXO URI');
+    process.exit(1);
+  }
+
+  const parsed = parseTxoUri(uri);
+
+  // Check if a specific field was requested
+  if (options.length > 0) {
+    for (const option of options) {
+      if (option.startsWith('--')) {
+        const field = option.substring(2);
+        if (parsed[field] !== undefined) {
+          console.log(parsed[field]);
+          process.exit(0);
+        } else {
+          console.error(`Error: Field "${field}" not found in parsed URI`);
+          process.exit(1);
+        }
+      }
+    }
+  } else {
+    // Output the full JSON
+    console.log(JSON.stringify(parsed, null, 2));
+  }
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+} 

package/index.js

@@ -0,0 +1,152 @@
+/**
+ * TXO URI Parser
+ * Implementation of the TXO URI Specification (v0.1)
+ * 
+ * Format: txo:<network>:<txid>:<output>?key=value&key=value...
+ */
+
+/**
+ * Parse a TXO URI and return a JSON object
+ * @param {string} uri - The TXO URI to parse
+ * @returns {object} - Parsed result as JSON
+ * @throws {Error} - If URI format is invalid
+ */
+export function parseTxoUri (uri) {
+  if (!uri || typeof uri !== 'string') {
+    throw new Error('Invalid URI: URI must be a non-empty string');
+  }
+
+  // Split the URI into its components
+  const [scheme, network, txid, outputAndRest] = uri.split(':');
+
+  // Validate scheme
+  if (scheme !== 'txo') {
+    throw new Error('Invalid URI: Scheme must be "txo"');
+  }
+
+  // Validate network (allow lowercase letters and digits, 3-10 chars)
+  // Updated to match the specification - at least one letter and can include numbers
+  if (!network || !/^[a-z][a-z0-9]{2,9}$/.test(network)) {
+    throw new Error('Invalid URI: Network must be 3-10 characters (lowercase letters and digits), starting with a letter');
+  }
+
+  // Validate txid
+  if (!txid || !/^[0-9a-f]{64}$/.test(txid)) {
+    throw new Error('Invalid URI: TXID must be a 64-character lowercase hexadecimal');
+  }
+
+  if (!outputAndRest) {
+    throw new Error('Invalid URI: Missing output index');
+  }
+
+  // Split the output and query string
+  let output, queryString;
+  if (outputAndRest.includes('?')) {
+    [output, queryString] = outputAndRest.split('?');
+  } else {
+    output = outputAndRest;
+    queryString = '';
+  }
+
+  // Validate output
+  const outputNum = parseInt(output, 10);
+  if (isNaN(outputNum) || outputNum < 0 || outputNum > 4294967295 || !/^\d+$/.test(output)) {
+    throw new Error('Invalid URI: Output must be a non-negative integer (0-4294967295)');
+  }
+
+  // Parse query string
+  const queryParams = {};
+  if (queryString) {
+    const params = queryString.split('&');
+    params.forEach(param => {
+      if (param.includes('=')) {
+        const [key, value] = param.split('=');
+        // Convert key to lowercase for case-insensitivity
+        const normalizedKey = key.toLowerCase();
+
+        // Process specific key types
+        if (normalizedKey === 'amount') {
+          // Parse amount as a number
+          const amount = parseFloat(value);
+          if (!isNaN(amount)) {
+            queryParams[normalizedKey] = amount;
+          } else {
+            queryParams[normalizedKey] = value;
+          }
+        } else {
+          queryParams[normalizedKey] = value;
+        }
+      }
+    });
+  }
+
+  // Build the result object
+  const result = {
+    network,
+    txid,
+    output: outputNum,
+    ...queryParams
+  };
+
+  return result;
+}
+
+/**
+ * Validates if a string is a valid TXO URI
+ * @param {string} uri - The URI to validate
+ * @returns {boolean} - True if valid, false otherwise
+ */
+export function isValidTxoUri (uri) {
+  try {
+    parseTxoUri(uri);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Formats a JSON object into a TXO URI
+ * @param {object} data - The data to format
+ * @returns {string} - The formatted TXO URI
+ * @throws {Error} - If required fields are missing or invalid
+ */
+export function formatTxoUri (data) {
+  // Validate required fields
+  if (!data.network || !data.txid || data.output === undefined) {
+    throw new Error('Missing required fields: network, txid, and output are required');
+  }
+
+  // Validate network (allow lowercase letters and digits, 3-10 chars)
+  if (!data.network || !/^[a-z][a-z0-9]{2,9}$/.test(data.network)) {
+    throw new Error('Invalid network: must be 3-10 characters (lowercase letters and digits), starting with a letter');
+  }
+
+  // Validate txid
+  if (!/^[0-9a-f]{64}$/.test(data.txid)) {
+    throw new Error('Invalid txid: must be a 64-character lowercase hexadecimal');
+  }
+
+  // Validate output
+  const output = parseInt(data.output, 10);
+  if (isNaN(output) || output < 0 || output > 4294967295) {
+    throw new Error('Invalid output: must be a non-negative integer (0-4294967295)');
+  }
+
+  // Build the base URI
+  let uri = `txo:${data.network}:${data.txid}:${output}`;
+
+  // Add query parameters
+  const queryParams = [];
+  Object.entries(data).forEach(([key, value]) => {
+    if (!['network', 'txid', 'output'].includes(key) && value !== undefined) {
+      queryParams.push(`${key.toLowerCase()}=${encodeURIComponent(value)}`);
+    }
+  });
+
+  if (queryParams.length > 0) {
+    uri += `?${queryParams.join('&')}`;
+  }
+
+  return uri;
+} 

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "txo_parser",
+  "version": "0.0.1",
+  "description": "Parser for TXO URI Specification (v0.1)",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "txo-parser": "./cli.js"
+  },
+  "scripts": {
+    "test": "node test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sandy-mount/txo_parser.git"
+  },
+  "keywords": [
+    "txo",
+    "uri",
+    "parser",
+    "bitcoin",
+    "blockchain",
+    "cli"
+  ],
+  "author": "Melvin Carvalho",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/sandy-mount/txo_parser/issues"
+  },
+  "homepage": "https://github.com/sandy-mount/txo_parser#readme"
+}