x402-bch-axios 1.0.0 → 1.1.0

package/README.md

@@ -1,7 +1,60 @@
 # x402-bch-axios
 
-This is a placeholder for what will become the x402-bch-axios library.
+JavaScript helpers for handling HTTP 402 responses against Bitcoin Cash powered
+x402 endpoints. This package ports the `withPaymentInterceptor` experience from
+the TypeScript `x402-axios` client and adapts it for BCH UTXO payments.
 
-# Licence
+## Installation
+
+```bash
+npm install x402-bch-axios minimal-slp-wallet axios
+```
+
+The library depends on `minimal-slp-wallet` and assumes you are using ESM
+(`type: module`) in your project.
+
+## Usage
+
+```javascript
+import axios from 'axios'
+import {
+  createSigner,
+  withPaymentInterceptor
+} from 'x402-bch-axios'
+
+const signer = createSigner(process.env.PRIVATE_KEY_WIF, 2000)
+
+const api = withPaymentInterceptor(
+  axios.create({ baseURL: 'https://example.com' }),
+  signer,
+  // Optional payment requirements selector; defaults to BCH utxo
+  undefined,
+  // Optional BCH wallet config matching minimal-slp-wallet expectations
+  {
+    apiType: 'consumer-api',
+    bchServerURL: 'https://free-bch.fullstack.cash'
+  }
+)
+
+const response = await api.get('/premium-endpoint')
+console.log(response.data)
+```
+
+## API
+
+- `createSigner(privateKeyWIF, paymentAmountSats)` — build a BCH signer used to
+  sign x402 payment payloads and control default spend amounts.
+- `withPaymentInterceptor(axiosInstance, signer, selector?, config?)` — attach
+  an interceptor that:
+  - waits for a 402 response,
+  - selects the BCH `utxo` payment requirement (or uses your selector),
+  - funds or reuses a tracked UTXO,
+  - replays the request with the `X-PAYMENT` header.
+- `selectPaymentRequirements(accepts)` — utility for filtering BCH
+  requirements.
+- `createPaymentHeader(...)` — exposed for advanced integrations that need
+  direct x402 payload handling.
+
+## Licence
 
 [MIT](LICENSE.md)

package/index.js

@@ -1,23 +1,233 @@
 /*
-  An npm JavaScript library for front end web apps. Implements a minimal
-  Bitcoin Cash wallet.
+  x402-bch-axios
+
+  A BCH-focused port of the x402 Axios interceptor. The API mirrors the
+  TypeScript `withPaymentInterceptor` experience but intentionally omits
+  multi-network support and config typings that are not relevant for BCH.
+
+  Differences from the TypeScript implementation:
+  - Only supports BCH `utxo` payment requirements and BCH signers.
+  - Accepts an optional BCH server config instead of the generic `X402Config`.
+  - Does not expose multi-network signer helpers or type exports.
 */
 
-/* eslint-disable no-async-promise-executor */
+// External dependencies
+import BCHWallet from 'minimal-slp-wallet'
+import RetryQueue from '@chris.troutner/retry-queue'
+
+const currentUtxo = {
+  txid: null,
+  vout: null,
+  satsLeft: 0
+}
+
+/**
+ * Creates a BCH signer from a private key in WIF format.
+ *
+ * @param {string} privateKeyWIF - Private key in Wallet Import Format (WIF)
+ * @param {number} paymentAmountSats - Default spend amount for queued payments
+ * @returns {{ ecpair: any, address: string, wif: string, paymentAmountSats: number, signMessage: (message: string) => string }}
+ */
+export function createSigner (privateKeyWIF, paymentAmountSats) {
+  const wallet = new BCHWallet()
+  const bchjs = wallet.bchjs
+
+  const ecpair = bchjs.ECPair.fromWIF(privateKeyWIF)
+  const address = bchjs.ECPair.toCashAddress(ecpair)
+
+  return {
+    ecpair,
+    address,
+    wif: privateKeyWIF,
+    paymentAmountSats,
+    signMessage (message) {
+      return bchjs.BitcoinCash.signMessageWithPrivKey(privateKeyWIF, message)
+    }
+  }
+}
+
+export const createBCHSigner = createSigner
+
+/**
+ * Selects BCH `utxo` payment requirements from a 402 accepts array.
+ *
+ * @param {Array} accepts - Array of payment requirements objects
+ * @returns {Object} First BCH `utxo` payment requirement
+ */
+export function selectPaymentRequirements (accepts = []) {
+  const bchRequirements = accepts.filter(req => {
+    return req?.network === 'bch' && req?.scheme === 'utxo'
+  })
+
+  if (bchRequirements.length === 0) {
+    throw new Error('No BCH payment requirements found in 402 response')
+  }
+
+  return bchRequirements[0]
+}
+
+/**
+ * Builds the X-PAYMENT header payload for BCH transfers.
+ *
+ * @param {ReturnType<typeof createSigner>} signer
+ * @param {Object} paymentRequirements
+ * @param {number} x402Version
+ * @param {string|null} txid
+ * @param {number|null} vout
+ * @returns {Promise<string>}
+ */
+export async function createPaymentHeader (
+  signer,
+  paymentRequirements,
+  x402Version = 1,
+  txid = null,
+  vout = null
+) {
+  const wallet = new BCHWallet()
+  await wallet.walletInfoPromise
+
+  const authorization = {
+    from: signer.address,
+    to: paymentRequirements.payTo,
+    value: paymentRequirements.minAmountRequired,
+    txid,
+    vout,
+    amount: signer.paymentAmountSats
+  }
+
+  const messageToSign = JSON.stringify(authorization)
+  const signature = signer.signMessage(messageToSign)
+
+  const paymentHeader = {
+    x402Version,
+    scheme: paymentRequirements.scheme || 'utxo',
+    network: paymentRequirements.network || 'bch',
+    payload: {
+      signature,
+      authorization
+    }
+  }
+
+  return JSON.stringify(paymentHeader)
+}
+
+async function sendPayment (signer, paymentRequirements, bchServerConfig = {}) {
+  const { apiType, bchServerURL } = bchServerConfig
+  const paymentAmountSats = signer.paymentAmountSats || paymentRequirements.minAmountRequired
+
+  const bchWallet = new BCHWallet(signer.wif, {
+    interface: apiType,
+    restURL: bchServerURL
+  })
+  await bchWallet.initialize()
 
-// Global npm libraries
-import BCHJS from '@psf/bch-js'
+  const retryQueue = new RetryQueue()
+  const receivers = [
+    {
+      address: paymentRequirements.payTo,
+      amountSat: paymentAmountSats
+    }
+  ]
 
-// Local libraries
-import Util from './lib/util.js'
-const util = new Util()
+  const txid = await retryQueue.addToQueue(bchWallet.send.bind(bchWallet), receivers)
 
-class BoilerplateLib {
-  constructor () {
-    // Encapsulate dependencies
-    this.bchjs = new BCHJS()
-    this.util = util
+  return {
+    txid,
+    vout: 0,
+    satsSent: paymentAmountSats
   }
 }
 
-export default BoilerplateLib
+/**
+ * Adds a payment interceptor to an axios instance.
+ *
+ * @param {import('axios').AxiosInstance} axiosInstance
+ * @param {ReturnType<typeof createSigner>} signer
+ * @param {Function|Object} paymentRequirementsSelectorOrConfig - Optional selector or BCH server config
+ * @param {Object} maybeConfig - Optional BCH server config when a selector is provided
+ * @returns {import('axios').AxiosInstance}
+ */
+export function withPaymentInterceptor (
+  axiosInstance,
+  signer,
+  paymentRequirementsSelectorOrConfig,
+  maybeConfig
+) {
+  let paymentRequirementsSelector = selectPaymentRequirements
+  let bchServerConfig = {}
+
+  if (typeof paymentRequirementsSelectorOrConfig === 'function') {
+    paymentRequirementsSelector = paymentRequirementsSelectorOrConfig
+    if (maybeConfig) {
+      bchServerConfig = maybeConfig
+    }
+  } else if (paymentRequirementsSelectorOrConfig) {
+    bchServerConfig = paymentRequirementsSelectorOrConfig
+  }
+
+  axiosInstance.interceptors.response.use(
+    response => response,
+    async error => {
+      if (!error.response || error.response.status !== 402) {
+        return Promise.reject(error)
+      }
+
+      try {
+        const originalConfig = error.config
+        if (!originalConfig || !originalConfig.headers) {
+          return Promise.reject(new Error('Missing axios request configuration'))
+        }
+
+        if (originalConfig.__is402Retry) {
+          return Promise.reject(error)
+        }
+
+        const { x402Version, accepts } = error.response.data || {}
+        if (!accepts || !Array.isArray(accepts) || accepts.length === 0) {
+          return Promise.reject(new Error('No payment requirements found in 402 response'))
+        }
+
+        const paymentRequirements = paymentRequirementsSelector(accepts)
+        const cost = paymentRequirements.minAmountRequired
+
+        let txid = null
+        let vout = null
+        let satsLeft = null
+
+        if (!currentUtxo.txid || currentUtxo.satsLeft < cost) {
+          const payment = await sendPayment(signer, paymentRequirements, bchServerConfig)
+          txid = payment.txid
+          vout = payment.vout
+          satsLeft = payment.satsSent - cost
+        } else {
+          txid = currentUtxo.txid
+          vout = currentUtxo.vout
+          satsLeft = currentUtxo.satsLeft - cost
+        }
+
+        currentUtxo.txid = txid
+        currentUtxo.vout = vout
+        currentUtxo.satsLeft = satsLeft
+
+        const paymentHeader = await createPaymentHeader(
+          signer,
+          paymentRequirements,
+          x402Version || 1,
+          txid,
+          vout
+        )
+
+        originalConfig.__is402Retry = true
+        originalConfig.headers['X-PAYMENT'] = paymentHeader
+        originalConfig.headers['Access-Control-Expose-Headers'] = 'X-PAYMENT-RESPONSE'
+
+        const secondResponse = await axiosInstance.request(originalConfig)
+        return secondResponse
+      } catch (paymentError) {
+        return Promise.reject(paymentError)
+      }
+    }
+  )
+
+  return axiosInstance
+}

package/package.json

@@ -1,15 +1,13 @@
 {
   "name": "x402-bch-axios",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Axios wrapper for x402 payment protocol with Bitcoin Cash (BCH) support.",
   "main": "index.js",
   "type": "module",
   "scripts": {
     "start": "node index.js",
     "test": "npm run lint && TEST=unit c8 mocha test/unit/",
-    "test:integration": "mocha --timeout 25000 test/integration/",
     "lint": "standard --env mocha --fix",
-    "docs": "./node_modules/.bin/apidoc -i src/ -o docs",
     "coverage": "c8 --reporter=html mocha test/unit/ --exit"
   },
   "keywords": [
@@ -36,7 +34,7 @@
     "husky": "9.1.7",
     "lodash.clonedeep": "4.5.0",
     "mocha": "11.7.5",
-    "semantic-release": "25.0.2",
+    "semantic-release": "19.0.3",
     "sinon": "21.0.0",
     "standard": "17.1.2"
   },

package/apidoc.json

@@ -1,3 +0,0 @@
-{
-  "sampleUrl": null
-}