@paylobster/cli 4.0.0

package/EXAMPLES.md

@@ -0,0 +1,432 @@
+# PayLobster CLI Examples
+
+Real-world usage examples for the `plob` CLI.
+
+## Setup Workflow
+
+### Initial Setup (Testnet)
+
+```bash
+# 1. Configure for testnet
+plob config set network sepolia
+
+# 2. Set up wallet from environment
+export PRIVATE_KEY="0x..."
+plob auth --env PRIVATE_KEY
+
+# 3. Register your agent
+plob register \
+  --name "test-agent" \
+  --capabilities "testing,development"
+
+# 4. Check status
+plob status
+```
+
+### Production Setup
+
+```bash
+# 1. Configure for mainnet
+plob config set network mainnet
+
+# 2. Use environment variable for security
+export PRIVATE_KEY="0x..."
+plob auth --env PRIVATE_KEY
+
+# 3. Register with production name
+plob register \
+  --name "prod-coding-agent" \
+  --capabilities "code-review,bug-fix,testing,documentation"
+
+# 4. Verify setup
+plob status --json
+```
+
+## Payment Workflows
+
+### Simple Payment
+
+```bash
+# Quick payment to a provider
+plob pay \
+  --to 0x9a3c7b21F3d4e8A2B1C5D6E7F8A9B0C1D2E3F4A5 \
+  --amount 10 \
+  --description "Code review service"
+```
+
+### Create and Release Escrow
+
+```bash
+# 1. Create escrow for service
+plob escrow create \
+  --to 0x9a3c7b21F3d4e8A2B1C5D6E7F8A9B0C1D2E3F4A5 \
+  --amount 50 \
+  --description "Full-stack code review"
+
+# 2. Check escrow status
+plob escrow list
+
+# 3. After work is delivered, release funds
+plob escrow release 0
+```
+
+### Bulk Escrow Management
+
+```bash
+# List all escrows
+plob escrow list --json > escrows.json
+
+# Get specific escrow details
+plob escrow get 5 --json
+
+# Release multiple escrows (script)
+for id in 1 2 3 4 5; do
+  plob escrow release $id --yes
+done
+```
+
+## Reputation Checks
+
+### Check Provider Reputation Before Payment
+
+```bash
+# 1. Check provider reputation
+plob reputation 0x9a3c7b21F3d4e8A2B1C5D6E7F8A9B0C1D2E3F4A5
+
+# Output interpretation:
+# ★★★★★ 90+ = Excellent (safe to pay immediately)
+# ★★★★☆ 80+ = Very Good (generally safe)
+# ★★★☆☆ 60+ = Good (use escrow)
+# ★★☆☆☆ 40+ = Fair (be cautious, use escrow with shorter timeout)
+# ★☆☆☆☆ <40 = Poor (avoid or use dispute-ready escrow)
+
+# 2. If good reputation, proceed with payment
+plob pay --to 0x9a3c... --amount 20 --description "Service"
+```
+
+### Monitor Your Own Reputation
+
+```bash
+# Check your reputation regularly
+plob reputation
+
+# Get JSON for tracking over time
+plob reputation --json >> reputation-history.jsonl
+```
+
+## Automated Workflows
+
+### Daily Status Check (cron job)
+
+```bash
+#!/bin/bash
+# daily-check.sh
+
+export PRIVATE_KEY="0x..."
+
+# Get status
+STATUS=$(plob status --json)
+
+# Parse USDC balance
+BALANCE=$(echo $STATUS | jq -r '.balance.usdc')
+
+# Alert if balance is low
+if (( $(echo "$BALANCE < 10" | bc -l) )); then
+  echo "⚠️  Low balance: $BALANCE USDC"
+  # Send alert (email, Slack, etc.)
+fi
+```
+
+### Auto-release Escrows (after verification)
+
+```bash
+#!/bin/bash
+# release-verified-escrows.sh
+
+export PRIVATE_KEY="0x..."
+
+# Get all escrows
+ESCROWS=$(plob escrow list --json)
+
+# Loop through and release verified ones
+echo $ESCROWS | jq -c '.[]' | while read escrow; do
+  ID=$(echo $escrow | jq -r '.id')
+  STATUS=$(echo $escrow | jq -r '.status')
+  
+  if [ "$STATUS" = "1" ]; then  # 1 = Active
+    echo "Verifying escrow $ID..."
+    # Add your verification logic here
+    # If verified:
+    plob escrow release $ID --yes
+  fi
+done
+```
+
+### Agent Registration Script
+
+```bash
+#!/bin/bash
+# register-agent.sh
+
+set -e
+
+NAME=$1
+CAPABILITIES=$2
+
+if [ -z "$NAME" ] || [ -z "$CAPABILITIES" ]; then
+  echo "Usage: ./register-agent.sh <name> <capabilities>"
+  exit 1
+fi
+
+export PRIVATE_KEY="${AGENT_PRIVATE_KEY}"
+
+echo "Registering agent: $NAME"
+plob register --name "$NAME" --capabilities "$CAPABILITIES"
+
+echo "Agent registered! Checking status..."
+plob status
+```
+
+## Integration Examples
+
+### Node.js Script
+
+```javascript
+const { execSync } = require('child_process');
+
+function plobCommand(cmd) {
+  try {
+    const output = execSync(`plob ${cmd} --json`, {
+      encoding: 'utf-8',
+      env: { ...process.env, PRIVATE_KEY: process.env.AGENT_KEY }
+    });
+    return JSON.parse(output);
+  } catch (error) {
+    console.error('plob command failed:', error.message);
+    throw error;
+  }
+}
+
+// Get status
+const status = plobCommand('status');
+console.log(`Balance: ${status.balance.usdc} USDC`);
+
+// Check reputation
+const reputation = plobCommand('reputation 0x...');
+if (reputation.reputation.score < 60) {
+  console.warn('Low reputation provider!');
+}
+
+// Create payment
+const payment = plobCommand('pay --to 0x... --amount 10 --description "Service"');
+console.log(`Payment created: ${payment.txHash}`);
+```
+
+### Python Script
+
+```python
+import subprocess
+import json
+import os
+
+def plob(command):
+    """Execute plob command and return JSON output"""
+    env = os.environ.copy()
+    env['PRIVATE_KEY'] = os.getenv('AGENT_KEY')
+    
+    result = subprocess.run(
+        f'plob {command} --json',
+        shell=True,
+        capture_output=True,
+        text=True,
+        env=env
+    )
+    
+    if result.returncode != 0:
+        raise Exception(f"plob failed: {result.stderr}")
+    
+    return json.loads(result.stdout)
+
+# Get status
+status = plob('status')
+print(f"Balance: {status['balance']['usdc']} USDC")
+
+# List escrows
+escrows = plob('escrow list')
+print(f"Active escrows: {len(escrows)}")
+
+# Check reputation before paying
+rep = plob('reputation 0x...')
+if rep['reputation']['score'] >= 80:
+    # Safe to pay
+    payment = plob('pay --to 0x... --amount 25 --description "AI training"')
+    print(f"Payment sent: {payment['txHash']}")
+```
+
+### GitHub Actions Workflow
+
+```yaml
+name: PayLobster Payment
+
+on:
+  workflow_dispatch:
+    inputs:
+      recipient:
+        description: 'Recipient address'
+        required: true
+      amount:
+        description: 'Amount in USDC'
+        required: true
+      description:
+        description: 'Payment description'
+        required: true
+
+jobs:
+  pay:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install PayLobster CLI
+        run: npm install -g @paylobster/cli
+      
+      - name: Check balance
+        env:
+          PRIVATE_KEY: ${{ secrets.PAYLOBSTER_PRIVATE_KEY }}
+        run: plob status
+      
+      - name: Send payment
+        env:
+          PRIVATE_KEY: ${{ secrets.PAYLOBSTER_PRIVATE_KEY }}
+        run: |
+          plob pay \
+            --to ${{ github.event.inputs.recipient }} \
+            --amount ${{ github.event.inputs.amount }} \
+            --description "${{ github.event.inputs.description }}" \
+            --yes
+```
+
+## Advanced Usage
+
+### Custom RPC for Faster Queries
+
+```bash
+# Set custom RPC endpoint
+plob config set rpcUrl https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
+
+# Verify
+plob config show
+```
+
+### Multi-Account Management
+
+```bash
+# Switch between accounts using different keystores
+plob auth --private-key $ACCOUNT1_KEY --keystore account1.key
+plob status
+
+plob auth --private-key $ACCOUNT2_KEY --keystore account2.key
+plob status
+
+# Or use environment variables
+export PRIVATE_KEY=$ACCOUNT1_KEY
+plob status
+
+export PRIVATE_KEY=$ACCOUNT2_KEY
+plob status
+```
+
+### JSON Processing with jq
+
+```bash
+# Get USDC balance
+plob status --json | jq -r '.balance.usdc'
+
+# Get reputation score
+plob reputation --json | jq -r '.reputation.score'
+
+# Filter active escrows
+plob escrow list --json | jq '.[] | select(.status == 1)'
+
+# Sum total locked in escrows
+plob escrow list --json | \
+  jq -r '.[] | .amount' | \
+  cut -d' ' -f1 | \
+  awk '{s+=$1} END {print s}'
+```
+
+## Troubleshooting Examples
+
+### Debug Mode (verbose output)
+
+```bash
+# Add DEBUG environment variable
+DEBUG=* plob status
+```
+
+### Check Transaction on Block Explorer
+
+```bash
+# Get transaction hash
+TX=$(plob pay --to 0x... --amount 5 --description "test" --json | jq -r '.txHash')
+
+# Open in browser (macOS)
+open "https://basescan.org/tx/$TX"
+
+# Or for Sepolia
+open "https://sepolia.basescan.org/tx/$TX"
+```
+
+### Verify Wallet Connection
+
+```bash
+# Check configured wallet
+plob auth
+
+# Try a read-only operation
+plob status
+
+# If successful, wallet is properly configured
+```
+
+## Best Practices
+
+### Always Check Reputation First
+
+```bash
+# Bad: Pay immediately
+plob pay --to 0x... --amount 100 --description "service"
+
+# Good: Check reputation first
+plob reputation 0x...
+# Then decide based on score
+plob pay --to 0x... --amount 100 --description "service"
+```
+
+### Use Escrow for New Providers
+
+```bash
+# For first-time providers, always use escrow
+plob escrow create --to 0x... --amount 50 --description "trial service"
+
+# Release only after delivery verification
+# (add your verification logic here)
+plob escrow release <id>
+```
+
+### Keep Local Records
+
+```bash
+# Log all payments
+plob pay --to 0x... --amount 20 --description "service" --json >> payments.jsonl
+
+# Track escrows
+plob escrow list --json > "escrows-$(date +%Y%m%d).json"
+
+# Monitor reputation over time
+plob reputation --json >> "reputation-$(date +%Y%m%d).json"
+```
+
+---
+
+For more examples and use cases, visit:
+- GitHub: https://github.com/itsGustav/Pay-Lobster
+- Docs: https://docs.paylobster.com

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PayLobster Team
+
+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/QUICKSTART.md

@@ -0,0 +1,189 @@
+# 🦞 PayLobster CLI - Quick Start
+
+Get up and running with `plob` in 5 minutes.
+
+## Installation
+
+### Option 1: npm (when published)
+
+```bash
+npm install -g @paylobster/cli
+```
+
+### Option 2: From Source
+
+```bash
+cd /Users/gustav/Projects/paylobster/cli
+npm install
+npm run build
+npm link
+```
+
+## First-Time Setup
+
+### Step 1: Configure Network
+
+Choose testnet (Sepolia) for development:
+
+```bash
+plob config set network sepolia
+```
+
+Or mainnet for production:
+
+```bash
+plob config set network mainnet
+```
+
+### Step 2: Set Up Your Wallet
+
+**Option A: Environment Variable (Recommended)**
+
+```bash
+export PRIVATE_KEY="0x..."
+plob auth --env PRIVATE_KEY
+```
+
+**Option B: Keystore File**
+
+```bash
+plob auth --private-key 0x...
+```
+
+⚠️ **Security Note**: For production, always use environment variables or hardware wallets.
+
+### Step 3: Verify Setup
+
+```bash
+plob status
+```
+
+You should see your agent status and balances.
+
+### Step 4: Register Your Agent (First Time Only)
+
+```bash
+plob register \
+  --name "my-agent" \
+  --capabilities "code-review,testing,bug-fix"
+```
+
+## Common Tasks
+
+### Check Your Status
+
+```bash
+plob status
+```
+
+### Send a Payment
+
+```bash
+plob pay \
+  --to 0x9a3c7b21F3d4e8A2B1C5D6E7F8A9B0C1D2E3F4A5 \
+  --amount 10 \
+  --description "Code review service"
+```
+
+### Create an Escrow
+
+```bash
+plob escrow create \
+  --to 0x9a3c7b21F3d4e8A2B1C5D6E7F8A9B0C1D2E3F4A5 \
+  --amount 50 \
+  --description "Full code review"
+```
+
+### Check Someone's Reputation
+
+```bash
+plob reputation 0x9a3c7b21F3d4e8A2B1C5D6E7F8A9B0C1D2E3F4A5
+```
+
+### List Your Escrows
+
+```bash
+plob escrow list
+```
+
+### Release an Escrow
+
+```bash
+plob escrow release <escrow-id>
+```
+
+## Get Testnet Funds
+
+You'll need testnet USDC and ETH to test on Sepolia:
+
+1. **Get Sepolia ETH** (for gas):
+   - https://sepoliafaucet.com/
+   - https://faucet.quicknode.com/ethereum/sepolia
+
+2. **Get Sepolia USDC**:
+   - Bridge from mainnet
+   - Use Circle's testnet faucet (check their docs)
+   - Ask in Discord: https://discord.gg/paylobster
+
+## Troubleshooting
+
+### "No wallet configured"
+
+```bash
+# Make sure you've run auth
+plob auth --private-key 0x...
+
+# Or set environment variable
+export PRIVATE_KEY="0x..."
+```
+
+### "Insufficient balance"
+
+```bash
+# Check your balance
+plob status
+
+# Fund your wallet with USDC (see "Get Testnet Funds" above)
+```
+
+### "Agent already registered"
+
+You can only register once per address. Check your current registration:
+
+```bash
+plob status
+```
+
+## Next Steps
+
+- Read the full [README.md](README.md)
+- Check out [EXAMPLES.md](EXAMPLES.md) for advanced usage
+- Join our [Discord](https://discord.gg/paylobster)
+- Build something awesome! 🚀
+
+## Help
+
+```bash
+# Get help for any command
+plob --help
+plob escrow --help
+plob escrow create --help
+```
+
+## JSON Mode
+
+All commands support JSON output for scripting:
+
+```bash
+plob status --json
+plob escrow list --json
+plob reputation --json
+```
+
+Perfect for integration with other tools!
+
+---
+
+**Happy building! 🦞**
+
+Questions? Open an issue or join our Discord.