vibecash 0.1.0

package/README.md

@@ -0,0 +1,642 @@
+# vibecash
+
+Payment infrastructure CLI for AI agents and developers.
+
+[![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
+
+```bash
+# 1. Create wallet (saves credentials to ~/.vibecash/config.json)
+vibecash wallet create
+
+# 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
+
+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
+```
+
+---
+
+## Payment Links (Recommended)
+
+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
+
+```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}"
+```
+
+Output:
+```json
+{
+  "id": "plink_xxx",
+  "url": "https://pay.vibecash.dev/p/plink_xxx",
+  "amount": 999,
+  "currency": "USD",
+  "active": true
+}
+```
+
+### 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"
+}
+```
+
+### 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
+
+```bash
+vibecash create 19.99 --monthly -d "Pro Plan"
+```
+
+> **Note:** Subscriptions only support card payments. WeChat Pay, Alipay, and PayNow are one-time payment methods only.
+
+### Create a yearly subscription with trial
+
+```bash
+vibecash create 99.99 --yearly -d "Annual Plan" --trial-days 14
+```
+
+### Full product + price + checkout workflow
+
+```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
+```
+
+---
+
+## 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.
+
+```bash
+vibecash create <amount> [options]
+```
+
+**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:**
+
+```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 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.
+
+```bash
+vibecash wallet claim
+```
+
+---
+
+### `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`) |
+
+```bash
+vibecash product get prod_ZkRdRurL0CSS2OXPEhmHBw
+```
+
+---
+
+### `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`
+
+```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 |
+
+```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 price list`
+
+List all prices, optionally filtered by product.
+
+```bash
+vibecash price list [options]
+```
+
+| Option | Description |
+|---|---|
+| `-p, --product <id>` | Filter prices by product ID |
+
+```bash
+# All prices
+vibecash price list
+
+# Prices for a specific product
+vibecash price list --product prod_xxx
+```
+
+---
+
+### `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) |
+
+```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
+```
+
+#### `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
+```
+
+---
+
+### `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]
+```
+
+| Argument | Description |
+|---|---|
+| `id` | Customer ID (`cus_xxx`) |
+
+| Option | Description |
+|---|---|
+| `-r, --return-url <url>` | URL to return to after the customer finishes |
+
+```bash
+vibecash customer portal cus_xxx --return-url https://mysite.com/account
+```
+
+---
+
+### `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`
+
+Resume a previously canceled subscription (only if it hasn't expired yet).
+
+```bash
+vibecash subscription resume <id>
+```
+
+| Argument | Description |
+|---|---|
+| `id` | Subscription ID (`sub_xxx`) |
+
+---
+
+## Output Formats
+
+By default, all commands output JSON. Use `--human` for formatted text.
+
+```bash
+# JSON output (default, good for scripts and piping)
+vibecash wallet status
+
+# Human-readable output
+vibecash wallet status --human
+```
+
+Set the default format via environment variable:
+
+```bash
+export AIPAY_OUTPUT=human
+```
+
+---
+
+## 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