facinet 1.0.0 → 2.0.1

package/README.md

@@ -1,25 +1,193 @@
-# Facinet CLI
+# Facinet
 
-> Command-line tool for the x402 Facilitator Network
+> JavaScript SDK and CLI tool for the x402 Facilitator Network
 
-Make payments and manage facilitators on the x402 decentralized payment network powered by Avalanche.
+Make gasless USDC payments and manage facilitators on the x402 decentralized payment network powered by Avalanche.
 
 ## Features
 
-- 💳 **Make Payments** - Pay via x402 using gasless USDC transfers
+- 💳 **Make Payments** - Gasless USDC transfers via ERC-3009
 - 🎲 **Random Facilitator Selection** - Fair distribution across network
-- 🚀 **Create Facilitators** - Set up your own payment facilitator
-- 📊 **Manage & Monitor** - Check status, balance, and activity
-- 🔐 **Secure** - Local wallet management with encryption
+- 🌐 **Multi-Platform** - Works in browser (MetaMask) and Node.js
+- 🚀 **Easy Integration** - Simple SDK for developers
+- 📊 **CLI Tool** - Command-line interface for payments and management
+- 🔐 **Secure** - Wallet management with encryption
 - ⚡ **Fast** - Built on Avalanche for sub-second finality
 
 ## Installation
 
+### As a Library (SDK)
+
+```bash
+npm install facinet
+```
+
+### As a CLI Tool
+
 ```bash
 npm install -g facinet
 ```
 
-## Quick Start
+## SDK Usage
+
+### Browser (with MetaMask)
+
+```typescript
+import { Facinet } from 'facinet';
+
+// Initialize SDK
+const facinet = new Facinet({
+  network: 'avalanche', // or 'ethereum', 'polygon'
+});
+
+// Make a payment (MetaMask will prompt for signature)
+const result = await facinet.pay({
+  amount: '1',                              // Amount in USDC
+  recipient: '0xYourMerchantAddress',       // Where you want to receive payment
+});
+
+console.log('Payment successful!', result.txHash);
+console.log('Processed by:', result.facilitator.name);
+```
+
+### Node.js (with Private Key)
+
+```typescript
+import { Facinet } from 'facinet';
+
+// Initialize with private key
+const facinet = new Facinet({
+  privateKey: process.env.PRIVATE_KEY,
+  network: 'avalanche',
+});
+
+// Make a payment
+const result = await facinet.pay({
+  amount: '5',
+  recipient: '0xYourMerchantAddress',
+});
+
+console.log('Transaction:', result.txHash);
+```
+
+### Quick One-Liner
+
+```typescript
+import { Facinet } from 'facinet';
+
+// Quick payment without creating instance
+await Facinet.quickPay({
+  amount: '1',
+  recipient: '0xMerchantAddress',
+  privateKey: process.env.PRIVATE_KEY,
+});
+```
+
+### Get Available Facilitators
+
+```typescript
+const facinet = new Facinet();
+
+// Get all active facilitators
+const facilitators = await facinet.getFacilitators();
+console.log(`${facilitators.length} active facilitators`);
+
+// Get a random facilitator
+const randomFacilitator = await facinet.selectRandomFacilitator();
+console.log('Selected:', randomFacilitator.name);
+```
+
+### SDK Configuration Options
+
+```typescript
+interface FacinetConfig {
+  apiUrl?: string;       // Default: 'https://x402-avalanche-chi.vercel.app'
+  privateKey?: string;   // For Node.js (not needed in browser)
+  network?: 'avalanche' | 'ethereum' | 'polygon';  // Default: 'avalanche'
+  rpcUrl?: string;       // Custom RPC URL (optional)
+}
+```
+
+### TypeScript Support
+
+Facinet is written in TypeScript and includes full type definitions:
+
+```typescript
+import type {
+  FacinetConfig,
+  PaymentParams,
+  PaymentResult,
+  Facilitator
+} from 'facinet';
+
+const config: FacinetConfig = {
+  network: 'avalanche',
+};
+
+const params: PaymentParams = {
+  amount: '1',
+  recipient: '0x...',
+};
+```
+
+### React Example
+
+```tsx
+import { useState } from 'react';
+import { Facinet } from 'facinet';
+
+function PaymentButton() {
+  const [loading, setLoading] = useState(false);
+  const [txHash, setTxHash] = useState('');
+
+  const handlePayment = async () => {
+    setLoading(true);
+    try {
+      const facinet = new Facinet({ network: 'avalanche' });
+
+      const result = await facinet.pay({
+        amount: '1',
+        recipient: '0xYourMerchantAddress',
+      });
+
+      setTxHash(result.txHash);
+      alert('Payment successful!');
+    } catch (error) {
+      console.error('Payment failed:', error);
+      alert('Payment failed');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handlePayment} disabled={loading}>
+        {loading ? 'Processing...' : 'Pay 1 USDC'}
+      </button>
+      {txHash && (
+        <p>Transaction: <a href={`https://testnet.snowtrace.io/tx/${txHash}`} target="_blank">
+          {txHash.slice(0, 10)}...
+        </a></p>
+      )}
+    </div>
+  );
+}
+```
+
+### How SDK Payments Work
+
+1. **Initialize SDK** - Create Facinet instance with your config
+2. **Random Facilitator** - SDK automatically picks random active facilitator
+3. **Sign Authorization** - User signs ERC-3009 authorization (gasless!)
+4. **Facilitator Executes** - Facilitator submits transaction and pays gas
+5. **Payment Complete** - USDC transferred to YOUR merchant address
+
+**Key Point:** The `recipient` you specify in `pay()` is where YOU receive payment. The SDK automatically handles facilitator selection and gas payment.
+
+## CLI Usage
+
+### Quick Start
 
 ### 1. Connect Your Wallet
 
@@ -219,6 +387,9 @@ facinet --help
 ```
 facinet/
 ├── src/
+│   ├── sdk/
+│   │   ├── Facinet.ts    # Main SDK class
+│   │   └── types.ts      # TypeScript types
 │   ├── commands/
 │   │   ├── connect.ts    # Wallet connection
 │   │   ├── pay.ts        # Payment processing
@@ -226,7 +397,9 @@ facinet/
 │   ├── utils/
 │   │   ├── config.ts     # Configuration management
 │   │   └── api.ts        # API client
+│   ├── sdk.ts            # SDK exports
 │   └── index.ts          # CLI entry point
+├── dist/                 # Compiled JavaScript
 ├── package.json
 ├── tsconfig.json
 └── README.md