vibecash 0.1.1 → 0.1.3

package/README.md

@@ -2,641 +2,190 @@
 
 VibeCash - Payment infrastructure for AI agents.
 
-[![npm version](https://img.shields.io/npm/v/vibecash.svg)](https://www.npmjs.com/package/vibecash)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## Install
-
 ```bash
 npm install -g vibecash
 ```
 
-## Quick Start
+## TL;DR - Accept Payments in 30 Seconds
 
 ```bash
-# 1. Create wallet (saves credentials to ~/.vibecash/config.json)
+# 1. Create wallet (one-time setup)
 vibecash wallet create
+# Saves credentials to ~/.vibecash/config.json
 
-# 2. Create a reusable payment link
-vibecash link create 9.99 --name "My Product" --success-url "https://myapp.com/thanks#session_id={CHECKOUT_SESSION_ID}"
-
-# 3. Share the URL - each visitor gets their own checkout session
-# Output: { "url": "https://pay.vibecash.dev/p/plink_xxx", ... }
-
-# 4. Verify payment (after user returns to your success URL)
-vibecash checkout get cs_xxx
-# Check: status === "complete"
-```
-
-## Environment Variables
-
-```bash
-VIBECASH_SECRET=sk_live_xxx     # API secret (or use ~/.vibecash/config.json)
-VIBECASH_API_URL=https://api.vibecash.dev  # API endpoint (default)
-```
-
-## All Commands
-
-```
-vibecash wallet create          # Create wallet, get API credentials
-vibecash wallet info            # Show balance and status
-vibecash wallet claim           # Generate dashboard claim link
-
-vibecash link create <amount>   # Create reusable payment link (recommended)
-vibecash link list              # List payment links
-vibecash link get <id>          # Get link details
-vibecash link activate <id>     # Activate link
-vibecash link deactivate <id>   # Deactivate link
-
-vibecash checkout create        # Create one-time checkout session
-vibecash checkout get <id>      # Get session status
+# 2. Create a payment link
+vibecash link create 9.99 --name "My Product"
+# Returns: { "url": "https://pay.vibecash.dev/p/plink_xxx", ... }
 
-vibecash product create <name>  # Create product
-vibecash product list           # List products
-vibecash product get <id>       # Get product
-
-vibecash price create <prod_id> <amount>  # Create price
-vibecash price list             # List prices
-
-vibecash subscription list      # List subscriptions
-vibecash subscription get <id>  # Get subscription
-vibecash subscription cancel <id>   # Cancel subscription
-vibecash subscription resume <id>   # Resume subscription
-
-vibecash customer create <email>    # Create customer
-vibecash customer list          # List customers
-vibecash customer get <id>      # Get customer
-vibecash customer portal <id>   # Generate customer portal URL
-
-vibecash create <amount>        # Quick: create checkout in one command
-```
-
-## Output Format
-
-```bash
-vibecash --json <command>    # JSON output (default, best for scripts/AI)
-vibecash --human <command>   # Human-readable tables
+# 3. Send URL to customer, they pay, done!
 ```
 
 ---
 
-## Payment Links (Recommended)
+## Quick Reference
 
-Payment Links are **reusable URLs** - each visitor automatically gets their own checkout session. Perfect for:
-- Static websites
-- AI agents
-- Sharing on social media
-- QR codes
+### Payment Links (Recommended)
 
 ```bash
-# Create payment link with success redirect
-vibecash link create 9.99 \
-  --name "Pro Plan" \
-  --description "Unlock all features" \
-  --currency USD \
-  --success-url "https://myapp.com/thanks#session_id={CHECKOUT_SESSION_ID}"
+vibecash link create <amount>                    # Create reusable payment URL
+vibecash link create 19.99 --name "Pro" --currency USD
+vibecash link create 9.99 --success-url "https://myapp.com/thanks#session_id={CHECKOUT_SESSION_ID}"
+vibecash link list                               # List all links
+vibecash link get <id>                           # Get link details
+vibecash link deactivate <id>                    # Disable a link
 ```
 
-Output:
-```json
-{
-  "id": "plink_xxx",
-  "url": "https://pay.vibecash.dev/p/plink_xxx",
-  "amount": 999,
-  "currency": "USD",
-  "active": true
-}
-```
+### Verify Payment
 
-### Verify Payment in Your App
-
-After payment, user is redirected to your success URL with session ID in the hash:
-```
-https://myapp.com/thanks#session_id=cs_xxx
-```
-
-Verify the payment:
-```javascript
-// Browser JavaScript
-const sessionId = new URLSearchParams(location.hash.slice(1)).get('session_id');
-const res = await fetch(`https://api.vibecash.dev/v1/checkout/sessions/${sessionId}`);
-const { session } = await res.json();
-if (session.status === 'complete') {
-  // Payment successful - unlock content
-  localStorage.setItem('unlocked', 'true');
-}
-```
-
-Or via CLI:
 ```bash
-vibecash checkout get cs_xxx
-# Look for: "status": "complete"
-```
-
----
-
-## Configuration
-
-The CLI reads configuration from two sources (environment variables take precedence):
-
-| Environment Variable | Description | Default |
-|---|---|---|
-| `AIPAY_SECRET` | Wallet API secret (`sk_live_...`) | Read from `~/.vibecash/config.json` |
-| `AIPAY_API_URL` | API server URL | `https://api.vibecash.dev` |
-| `AIPAY_OUTPUT` | Output format (`json` or `human`) | `json` |
-
-Config file location: `~/.vibecash/config.json`
-
-```json
-{
-  "secret": "sk_live_xxx...",
-  "apiUrl": "https://api.vibecash.dev"
-}
+vibecash checkout get <session_id>
+# Response: { "session": { "status": "complete", ... } }
 ```
 
-### Global flags
-
-| Flag | Description |
-|---|---|
-| `--human` | Human-readable output (tables and formatted text) |
-| `--json` | JSON output (default) |
-| `--version` | Show version |
-| `--help` | Show help for any command |
-
----
-
-## Common Workflows
-
-### Collect a one-time payment
-
-```bash
-vibecash create 5.00 -d "Service fee"
-```
-
-### Create a monthly subscription
+### Wallet
 
 ```bash
-vibecash create 19.99 --monthly -d "Pro Plan"
+vibecash wallet create    # Create new wallet, get API key
+vibecash wallet info      # Show balance
+vibecash wallet claim     # Get dashboard access link
 ```
 
-> **Note:** Subscriptions only support card payments. WeChat Pay, Alipay, and PayNow are one-time payment methods only.
-
-### Create a yearly subscription with trial
+### One-Time Checkout
 
 ```bash
-vibecash create 99.99 --yearly -d "Annual Plan" --trial-days 14
+vibecash create 25.00 -d "Consulting"                    # Quick one-time payment
+vibecash checkout create --amount 50 --success-url URL   # With redirect
 ```
 
-### Full product + price + checkout workflow
+### Subscriptions
 
 ```bash
-# Step 1: Create a product
-vibecash product create "Premium Plan" -d "Full-featured plan"
-
-# Step 2: Create a recurring price for that product
-vibecash price create prod_xxx --amount 29.99 --type recurring --interval month
-
-# Step 3: Create a checkout session with the price
-vibecash checkout create --price price_xxx --success-url https://example.com/thanks
+vibecash create 9.99 --monthly -d "Pro Plan"             # Monthly subscription
+vibecash create 99 --yearly -d "Annual" --trial-days 14  # Yearly with trial
+vibecash subscription list                                # List all
+vibecash subscription cancel <id>                         # Cancel
 ```
 
----
-
-## Command Reference
-
-### `vibecash create` -- Quick Checkout
-
-The fastest way to generate a payment link. For one-time payments, it creates a checkout session directly. For subscriptions, it automatically creates the product, price, and checkout session in one step.
+### Products & Prices
 
 ```bash
-vibecash create <amount> [options]
+vibecash product create "Plan Name"                      # Create product
+vibecash price create <prod_id> 29.99 --type recurring --interval month
 ```
 
-**Arguments:**
-
-| Argument | Description |
-|---|---|
-| `amount` | Amount to charge in dollars (e.g. `9.99`, `1.00`, `250`) |
-
-**Options:**
-
-| Option | Description |
-|---|---|
-| `-d, --description <desc>` | Payment description (shown to customer) |
-| `--monthly` | Create a monthly subscription instead of one-time payment |
-| `--yearly` | Create a yearly subscription |
-| `--weekly` | Create a weekly subscription |
-| `--trial-days <days>` | Trial period in days (subscriptions only) |
-| `--success-url <url>` | URL to redirect after successful payment |
-| `--cancel-url <url>` | URL to redirect if customer cancels |
-| `--email <email>` | Pre-fill customer email |
-
-**Examples:**
+### Customers
 
 ```bash
-# One-time $1 payment
-vibecash create 1.00
-
-# $25 with description
-vibecash create 25.00 -d "Consulting hour"
-
-# Monthly subscription
-vibecash create 9.99 --monthly -d "Basic Plan"
-
-# Yearly with 7-day trial and customer email
-vibecash create 99.99 --yearly -d "Pro Plan" --trial-days 7 --email user@example.com
-
-# One-time with redirect URLs
-vibecash create 50.00 -d "Workshop" --success-url https://mysite.com/thanks --cancel-url https://mysite.com/cancel
+vibecash customer create --email user@example.com
+vibecash customer list
+vibecash customer portal <id>                            # Self-service portal URL
 ```
 
 ---
 
-### `vibecash wallet` -- Wallet Management
-
-#### `vibecash wallet create`
-
-Create a new wallet. The API secret is automatically saved to `~/.vibecash/config.json`.
-
-```bash
-vibecash wallet create
-```
-
-No options. Returns the wallet ID and secret.
-
-#### `vibecash wallet status`
-
-Show the current wallet's balance and status.
-
-```bash
-vibecash wallet status
-```
-
-Returns: wallet ID, status, balance, pending balance, currency, creation date.
-
-#### `vibecash wallet claim`
-
-Generate a claim link to transfer wallet ownership. The link expires in 7 days.
+## Environment Variables
 
 ```bash
-vibecash wallet claim
+VIBECASH_SECRET=sk_live_xxx      # API key (or use ~/.vibecash/config.json)
+VIBECASH_API_URL=https://api.vibecash.dev   # Default API endpoint
 ```
 
 ---
 
-### `vibecash product` -- Product Management
-
-Products represent what you are selling. Each product can have multiple prices.
-
-#### `vibecash product create`
-
-```bash
-vibecash product create <name> [options]
-```
-
-| Argument | Description |
-|---|---|
-| `name` | Product name (required) |
-
-| Option | Description |
-|---|---|
-| `-d, --description <desc>` | Product description |
-
-```bash
-vibecash product create "Starter Plan" -d "Basic features for individuals"
-```
-
-#### `vibecash product list`
-
-List all products in your wallet.
-
-```bash
-vibecash product list
-```
-
-#### `vibecash product get`
-
-Get details of a specific product.
-
-```bash
-vibecash product get <id>
-```
-
-| Argument | Description |
-|---|---|
-| `id` | Product ID (`prod_xxx`) |
+## Output Format
 
 ```bash
-vibecash product get prod_ZkRdRurL0CSS2OXPEhmHBw
+vibecash --json <command>    # JSON (default, best for AI/scripts)
+vibecash --human <command>   # Human-readable tables
 ```
 
 ---
 
-### `vibecash price` -- Price Management
-
-Prices define how much to charge for a product. A product can have multiple prices (e.g. monthly and yearly).
-
-#### `vibecash price create`
+## Integration Example: Static Website Paywall
 
-```bash
-vibecash price create <product_id> [options]
-```
-
-| Argument | Description |
-|---|---|
-| `product_id` | Product ID to attach the price to (`prod_xxx`) |
-
-| Option | Required | Description |
-|---|---|---|
-| `-a, --amount <amount>` | Yes | Price in dollars (e.g. `9.99`) |
-| `-t, --type <type>` | Yes | `one_time` or `recurring` |
-| `-c, --currency <code>` | No | Currency code (default: `USD`). Supports: USD, EUR, GBP, CAD, AUD, SGD, CNY, JPY, HKD |
-| `-i, --interval <interval>` | When recurring | Billing interval: `day`, `week`, `month`, or `year` |
-| `--interval-count <n>` | No | Number of intervals between billings (default: `1`). E.g. `--interval month --interval-count 3` = quarterly |
-| `--trial-days <days>` | No | Free trial period in days |
+### Step 1: Create Payment Link with Redirect
 
 ```bash
-# One-time price
-vibecash price create prod_xxx --amount 29.99 --type one_time
-
-# Monthly recurring
-vibecash price create prod_xxx --amount 9.99 --type recurring --interval month
-
-# Yearly recurring in SGD
-vibecash price create prod_xxx --amount 108.00 --type recurring --interval year --currency SGD
-
-# Quarterly (every 3 months) with 14-day trial
-vibecash price create prod_xxx --amount 49.99 --type recurring --interval month --interval-count 3 --trial-days 14
+vibecash link create 4.99 \
+  --name "Premium Access" \
+  --success-url "https://yoursite.com/unlock#session_id={CHECKOUT_SESSION_ID}"
 ```
 
-#### `vibecash price list`
+### Step 2: Verify Payment in JavaScript
 
-List all prices, optionally filtered by product.
-
-```bash
-vibecash price list [options]
-```
-
-| Option | Description |
-|---|---|
-| `-p, --product <id>` | Filter prices by product ID |
+```javascript
+// After payment, user lands on: https://yoursite.com/unlock#session_id=cs_xxx
+const sessionId = new URLSearchParams(location.hash.slice(1)).get('session_id');
 
-```bash
-# All prices
-vibecash price list
+if (sessionId) {
+  const res = await fetch(`https://api.vibecash.dev/v1/checkout/sessions/${sessionId}`);
+  const { session } = await res.json();
 
-# Prices for a specific product
-vibecash price list --product prod_xxx
+  if (session.status === 'complete') {
+    localStorage.setItem('paid', 'true');
+    // Unlock content
+  }
+}
 ```
 
 ---
 
-### `vibecash checkout` -- Checkout Sessions
-
-Checkout sessions represent a single payment or subscription attempt. Each session has a unique URL where customers complete their payment. Sessions expire after 24 hours.
-
-#### `vibecash checkout create`
-
-```bash
-vibecash checkout create [options]
-```
-
-You must provide either `--price` or `--amount`:
-
-| Option | Description |
-|---|---|
-| `-p, --price <id>` | Use an existing price ID (`price_xxx`) |
-| `-a, --amount <amount>` | Create an inline one-time charge (in dollars) |
-| `-d, --description <desc>` | Description for inline charge (use with `--amount`) |
-| `-m, --mode <mode>` | `payment` (default) or `subscription` |
-| `--success-url <url>` | Redirect URL after successful payment |
-| `--cancel-url <url>` | Redirect URL if customer cancels |
-| `--email <email>` | Pre-fill customer email |
-| `--trial-days <days>` | Trial period (subscriptions only) |
+## API Endpoints
 
-```bash
-# Inline one-time charge
-vibecash checkout create --amount 15.00 -d "T-shirt"
-
-# Using an existing price
-vibecash checkout create --price price_xxx --success-url https://mysite.com/thanks
-
-# Subscription checkout
-vibecash checkout create --price price_xxx --mode subscription --email user@example.com
-```
+| Action | CLI Command | API Endpoint |
+|--------|-------------|--------------|
+| Create wallet | `wallet create` | `POST /v1/wallets` |
+| Get wallet | `wallet info` | `GET /v1/wallets/current` |
+| Create payment link | `link create` | `POST /v1/payment_links` |
+| List payment links | `link list` | `GET /v1/payment_links` |
+| Get checkout session | `checkout get` | `GET /v1/checkout/sessions/:id` |
+| Create checkout | `checkout create` | `POST /v1/checkout/sessions` |
+| List products | `product list` | `GET /v1/products` |
+| List subscriptions | `subscription list` | `GET /v1/subscriptions` |
 
-#### `vibecash checkout status`
-
-Check the status of a checkout session. Can optionally poll until the session completes.
-
-```bash
-vibecash checkout status <id> [options]
-```
-
-| Argument | Description |
-|---|---|
-| `id` | Checkout session ID (`cs_xxx`) |
-
-| Option | Description |
-|---|---|
-| `-w, --wait` | Poll every 2 seconds until session completes or expires |
-| `--timeout <ms>` | Max wait time in milliseconds (default: `300000` = 5 minutes) |
-
-```bash
-# Check once
-vibecash checkout status cs_xxx
-
-# Wait for completion (useful in scripts)
-vibecash checkout status cs_xxx --wait --timeout 60000
-```
+API Base URL: `https://api.vibecash.dev`
 
 ---
 
-### `vibecash customer` -- Customer Management
-
-#### `vibecash customer create`
-
-```bash
-vibecash customer create [options]
-```
-
-| Option | Required | Description |
-|---|---|---|
-| `-e, --email <email>` | Yes | Customer email address |
-| `-n, --name <name>` | No | Customer display name |
-
-```bash
-vibecash customer create --email alice@example.com --name "Alice"
-```
-
-#### `vibecash customer list`
-
-List all customers.
-
-```bash
-vibecash customer list
-```
-
-#### `vibecash customer get`
-
-Get details of a specific customer.
-
-```bash
-vibecash customer get <id>
-```
-
-| Argument | Description |
-|---|---|
-| `id` | Customer ID (`cus_xxx`) |
-
-#### `vibecash customer portal`
-
-Create a self-service portal session for a customer to manage their subscriptions and billing.
-
-```bash
-vibecash customer portal <id> [options]
-```
+## Supported Payment Methods
 
-| Argument | Description |
-|---|---|
-| `id` | Customer ID (`cus_xxx`) |
+| Method | One-time | Subscription |
+|--------|----------|--------------|
+| Credit/Debit Card | ✅ | ✅ |
+| WeChat Pay | ✅ | ❌ |
+| Alipay | ✅ | ❌ |
+| PayNow (SGD only) | ✅ | ❌ |
 
-| Option | Description |
-|---|---|
-| `-r, --return-url <url>` | URL to return to after the customer finishes |
+## Supported Currencies
 
-```bash
-vibecash customer portal cus_xxx --return-url https://mysite.com/account
-```
+USD, EUR, GBP, CAD, AUD, SGD, CNY, JPY, HKD
 
 ---
 
-### `vibecash subscription` -- Subscription Management
-
-#### `vibecash subscription list`
-
-```bash
-vibecash subscription list [options]
-```
-
-| Option | Description |
-|---|---|
-| `-c, --customer <id>` | Filter by customer ID |
-| `-s, --status <status>` | Filter by status (`active`, `canceled`, `past_due`, `trialing`) |
-
-```bash
-# All subscriptions
-vibecash subscription list
-
-# Active only
-vibecash subscription list --status active
-
-# For a specific customer
-vibecash subscription list --customer cus_xxx
-```
-
-#### `vibecash subscription get`
-
-```bash
-vibecash subscription get <id>
-```
-
-| Argument | Description |
-|---|---|
-| `id` | Subscription ID (`sub_xxx`) |
-
-#### `vibecash subscription cancel`
-
-Cancel a subscription. By default, cancels at the end of the current billing period.
-
-```bash
-vibecash subscription cancel <id> [options]
-```
-
-| Argument | Description |
-|---|---|
-| `id` | Subscription ID (`sub_xxx`) |
-
-| Option | Description |
-|---|---|
-| `--immediately` | Cancel right now instead of at period end |
-
-```bash
-# Cancel at period end (customer keeps access until then)
-vibecash subscription cancel sub_xxx
-
-# Cancel immediately
-vibecash subscription cancel sub_xxx --immediately
-```
-
-#### `vibecash subscription resume`
+## Common Patterns
 
-Resume a previously canceled subscription (only if it hasn't expired yet).
+### Create Subscription Product
 
 ```bash
-vibecash subscription resume <id>
-```
-
-| Argument | Description |
-|---|---|
-| `id` | Subscription ID (`sub_xxx`) |
-
----
-
-## Output Formats
+vibecash product create "Pro Plan"
+# Output: { "id": "prod_xxx", ... }
 
-By default, all commands output JSON. Use `--human` for formatted text.
-
-```bash
-# JSON output (default, good for scripts and piping)
-vibecash wallet status
+vibecash price create prod_xxx 19.99 --type recurring --interval month
+# Output: { "id": "price_xxx", ... }
 
-# Human-readable output
-vibecash wallet status --human
+vibecash checkout create --price price_xxx --mode subscription
+# Output: { "url": "https://pay.vibecash.dev/checkout/cs_xxx", ... }
 ```
 
-Set the default format via environment variable:
+### Poll for Payment Completion
 
 ```bash
-export AIPAY_OUTPUT=human
+vibecash checkout get cs_xxx --wait --timeout 60000
+# Waits up to 60 seconds for payment to complete
 ```
 
 ---
 
-## Supported Payment Methods
-
-| Method | One-time Payment | Subscription |
-|--------|-----------------|--------------|
-| Credit/Debit Card | ✅ | ✅ |
-| WeChat Pay | ✅ | ❌ |
-| Alipay | ✅ | ❌ |
-| PayNow (Singapore) | ✅ | ❌ |
-
-> Subscriptions require card payment because only cards support automatic recurring charges. QR code payment methods (WeChat, Alipay, PayNow) are for one-time payments only.
-
----
-
-## Supported Currencies
-
-USD, EUR, GBP, CAD, AUD, SGD, CNY, JPY, HKD
-
-> PayNow is only available for SGD transactions.
-
----
-
-## Amount Format
-
-All amounts are entered in **dollars** (or the main unit of the currency). The CLI converts them to cents internally.
-
-| You type | Stored as | Meaning |
-|---|---|---|
-| `1` | 100 | $1.00 |
-| `9.99` | 999 | $9.99 |
-| `0.50` | 50 | $0.50 |
-| `250` | 25000 | $250.00 |
-
----
-
 ## License
 
 MIT

package/dist/index.js

@@ -990,7 +990,7 @@ function createLinkCommand() {
 
 // src/index.ts
 var program = new Command9();
-program.name("vibecash").description("VibeCash - Payment infrastructure for AI agents").version("0.1.1");
+program.name("vibecash").description("VibeCash - Payment infrastructure for AI agents").version("0.1.3");
 program.addCommand(createWalletCommand());
 program.addCommand(createProductCommand());
 program.addCommand(createPriceCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibecash",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "VibeCash - Payment infrastructure for AI agents",
   "type": "module",
   "bin": {