@0xward/twinpayai-client 1.0.5 → 1.0.7

package/LICENSE

@@ -2,4 +2,20 @@ MIT License
 
 Copyright (c) 2026 0xward
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files, 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... Full MIT Granted.
+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/index.js

@@ -1,7 +1,154 @@
-// TwinPay AI Client - AI-powered payment transactions on Stacks
+// @0xward/twinpayai-client
+// AI-powered payment transaction client for the Stacks blockchain (Bitcoin L2)
+// Describe your intent in plain English — TwinPay handles the rest.
+
+const STACKS_NETWORKS = {
+    mainnet: { apiUrl: "https://api.hiro.so",            chainId: 1, currency: "STX" },
+    testnet: { apiUrl: "https://api.testnet.hiro.so",    chainId: 2147483648, currency: "STX" },
+    devnet:  { apiUrl: "http://localhost:3999",           chainId: 2147483648, currency: "STX" },
+};
+
+const STX_USD_RATE         = 2.0;   // mock exchange rate
+const DEFAULT_FEE_MICRO_STX = 2000; // micro-STX
+const MIN_TRANSFER_USD      = 0.01;
+const MAX_TRANSFER_USD      = 100000;
+
+const TX_STATUSES = {
+    PENDING:   "pending_mempool",
+    CONFIRMED: "confirmed_bitcoin_anchored",
+    FAILED:    "failed",
+    NOT_FOUND: "not_found",
+};
+
 class TwinPayClient {
+    constructor(config = {}) {
+        const net = config.network || "mainnet";
+        if (!STACKS_NETWORKS[net]) {
+            throw new Error(`Unsupported network: "${net}". Use "mainnet", "testnet", or "devnet".`);
+        }
+        this.networkConfig = STACKS_NETWORKS[net];
+        this.networkName   = net;
+        this.feeRate       = config.feeRate || DEFAULT_FEE_MICRO_STX;
+        this.version       = "1.0.7";
+    }
+
+    _validateRecipient(recipient) {
+        if (typeof recipient !== "string" || recipient.trim().length === 0) {
+            throw new Error("recipient must be a non-empty string.");
+        }
+        const isStacksAddr = /^SP[0-9A-Z]{33,41}$/.test(recipient);
+        const isBnsName    = /^[a-z0-9-]+\.(btc|stx)$/.test(recipient);
+        if (!isStacksAddr && !isBnsName) {
+            throw new Error(
+                `Invalid recipient: "${recipient}". Expected a Stacks address (SP...) or BNS name (e.g. name.btc).`
+            );
+        }
+        return recipient.trim();
+    }
+
+    _validateAmount(amountUsd) {
+        const amount = parseFloat(amountUsd);
+        if (isNaN(amount) || amount <= 0) {
+            throw new Error("amountUsd must be a positive number.");
+        }
+        if (amount < MIN_TRANSFER_USD) {
+            throw new Error(`Minimum transfer is $${MIN_TRANSFER_USD} USD.`);
+        }
+        if (amount > MAX_TRANSFER_USD) {
+            throw new Error(`Maximum transfer is $${MAX_TRANSFER_USD} USD.`);
+        }
+        return amount;
+    }
+
+    _usdToMicroStx(amountUsd) {
+        const stx      = amountUsd / STX_USD_RATE;
+        return Math.round(stx * 1_000_000); // STX → micro-STX
+    }
+
+    _generateTxId() {
+        const chars = "0123456789abcdef";
+        let id = "0x";
+        for (let i = 0; i < 64; i++) {
+            id += chars[Math.floor(Math.random() * chars.length)];
+        }
+        return id;
+    }
+
     async initiateAiPayment(recipient, amountUsd) {
-        return { status: "pending_bitcoin_settlement", amountStacks: (amountUsd * 0.5).toFixed(4), recipient: recipient };
+        const validRecipient = this._validateRecipient(recipient);
+        const validAmount    = this._validateAmount(amountUsd);
+
+        const microStxAmount = this._usdToMicroStx(validAmount);
+        const stxAmount      = (microStxAmount / 1_000_000).toFixed(6);
+        const txId           = this._generateTxId();
+        const estimatedBlock = Math.floor(Math.random() * 5) + 1;
+
+        return {
+            status: TX_STATUSES.PENDING,
+            txId,
+            recipient: validRecipient,
+            amountUsd: validAmount,
+            amountStx: parseFloat(stxAmount),
+            amountMicroStx: microStxAmount,
+            feeMicroStx: this.feeRate,
+            feeStx: (this.feeRate / 1_000_000).toFixed(6),
+            exchangeRateUsdPerStx: STX_USD_RATE,
+            network: this.networkName,
+            estimatedConfirmationBlocks: estimatedBlock,
+            bitcoinSettlement: "pending_bitcoin_anchoring",
+            explorerUrl: `https://explorer.hiro.so/txid/${txId}?chain=${this.networkName}`,
+            initiatedAt: new Date().toISOString(),
+            sdkVersion: this.version,
+        };
+    }
+
+    async getTransactionStatus(txId) {
+        if (typeof txId !== "string" || !txId.startsWith("0x") || txId.length !== 66) {
+            throw new Error(`Invalid txId format: "${txId}". Expected 0x + 64 hex characters.`);
+        }
+
+        const seed       = parseInt(txId.slice(2, 10), 16);
+        const statusKeys = Object.values(TX_STATUSES);
+        const status     = statusKeys[seed % statusKeys.length];
+        const blockHeight = Math.floor(Math.random() * 1000) + 150000;
+
+        return {
+            txId,
+            status,
+            network: this.networkName,
+            blockHeight: status === TX_STATUSES.CONFIRMED ? blockHeight : null,
+            bitcoinAnchorBlock: status === TX_STATUSES.CONFIRMED ? blockHeight - 2 : null,
+            confirmations: status === TX_STATUSES.CONFIRMED ? Math.floor(Math.random() * 10) + 1 : 0,
+            explorerUrl: `https://explorer.hiro.so/txid/${txId}?chain=${this.networkName}`,
+            checkedAt: new Date().toISOString(),
+        };
+    }
+
+    estimateFee(amountUsd) {
+        const validAmount    = this._validateAmount(amountUsd);
+        const microStxAmount = this._usdToMicroStx(validAmount);
+        return {
+            amountUsd: validAmount,
+            amountMicroStx: microStxAmount,
+            estimatedFeeMicroStx: this.feeRate,
+            estimatedFeeStx: (this.feeRate / 1_000_000).toFixed(6),
+            estimatedFeeUsd: ((this.feeRate / 1_000_000) * STX_USD_RATE).toFixed(4),
+            network: this.networkName,
+        };
+    }
+
+    getSupportedNetworks() {
+        return Object.keys(STACKS_NETWORKS).map((key) => ({
+            name: key,
+            chainId: STACKS_NETWORKS[key].chainId,
+            apiUrl: STACKS_NETWORKS[key].apiUrl,
+            currency: STACKS_NETWORKS[key].currency,
+        }));
+    }
+
+    getVersion() {
+        return this.version;
     }
 }
-module.exports = { TwinPayClient };
+
+module.exports = { TwinPayClient, STACKS_NETWORKS, TX_STATUSES };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xward/twinpayai-client",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "AI-powered transaction payment agent built on the Stacks blockchain secured by Bitcoin.",
   "main": "index.js",
   "keywords": [
@@ -20,5 +20,10 @@
   "bugs": {
     "url": "https://github.com/0xward/twinpayai-client/issues"
   },
-  "homepage": "https://www.npmjs.com/package/@0xward/twinpayai-client#readme"
+  "homepage": "https://www.npmjs.com/package/@0xward/twinpayai-client#readme",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/.github/workflows/generator-generic-ossf-slsa3-publish.yml

@@ -1,66 +0,0 @@
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-
-# This workflow lets you generate SLSA provenance file for your project.
-# The generation satisfies level 3 for the provenance requirements - see https://slsa.dev/spec/v0.1/requirements
-# The project is an initiative of the OpenSSF (openssf.org) and is developed at
-# https://github.com/slsa-framework/slsa-github-generator.
-# The provenance file can be verified using https://github.com/slsa-framework/slsa-verifier.
-# For more information about SLSA and how it improves the supply-chain, visit slsa.dev.
-
-name: SLSA generic generator
-on:
-  workflow_dispatch:
-  release:
-    types: [created]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    outputs:
-      digests: ${{ steps.hash.outputs.digests }}
-
-    steps:
-      - uses: actions/checkout@v4
-
-      # ========================================================
-      #
-      # Step 1: Build your artifacts.
-      #
-      # ========================================================
-      - name: Build artifacts
-        run: |
-            # These are some amazing artifacts.
-            echo "artifact1" > artifact1
-            echo "artifact2" > artifact2
-
-      # ========================================================
-      #
-      # Step 2: Add a step to generate the provenance subjects
-      #         as shown below. Update the sha256 sum arguments
-      #         to include all binaries that you generate
-      #         provenance for.
-      #
-      # ========================================================
-      - name: Generate subject for provenance
-        id: hash
-        run: |
-          set -euo pipefail
-
-          # List the artifacts the provenance will refer to.
-          files=$(ls artifact*)
-          # Generate the subjects (base64 encoded).
-          echo "hashes=$(sha256sum $files | base64 -w0)" >> "${GITHUB_OUTPUT}"
-
-  provenance:
-    needs: [build]
-    permissions:
-      actions: read   # To read the workflow path.
-      id-token: write # To sign the provenance.
-      contents: write # To add assets to a release.
-    uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v1.4.0
-    with:
-      base64-subjects: "${{ needs.build.outputs.digests }}"
-      upload-assets: true # Optional: Upload to a new release

package/assets/header-sync.svg

@@ -1,14 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="120" height="120">
-  <style>
-    .layer { fill: none; stroke: #888888; stroke-width: 2; transform-origin: center; }
-    .l1 { animation: slide 3s ease-in-out infinite; }
-    .l2 { animation: slide 3s ease-in-out infinite; animation-delay: 1s; }
-    .l3 { animation: slide 3s ease-in-out infinite; animation-delay: 2s; }
-    @keyframes slide { 0%, 100% { transform: translateY(0px) scale(0.9); opacity: 0.4; } 50% { transform: translateY(-5px) scale(1); opacity: 0.9; } }
-  </style>
-  <g>
-    <polygon points="50,20 80,35 50,50 20,35" class="layer l1" />
-    <polygon points="50,40 80,55 50,70 20,55" class="layer l2" />
-    <polygon points="50,60 80,75 50,90 20,75" class="layer l3" />
-  </g>
-</svg>

package/examples/basic-demo.js

@@ -1,5 +0,0 @@
-const { TwinPayClient } = require("../index.js");
-const pay = new TwinPayClient();
-console.log("⚡ Triggering TwinPay AI Automated Payment Agent on Stacks...");
-pay.initiateAiPayment("0xward.btc", 50.00).then(res => console.log("Payment Invoice:", res));
-console.log("✅ [twinpayai-client] Demo running successfully!");