cashclaw 1.0.0

package/skills/cashclaw-invoicer/SKILL.md

@@ -0,0 +1,395 @@
+---
+name: cashclaw-invoicer
+description: Handles invoice creation, payment link generation, payment status tracking, and automated reminders via Stripe API. Supports multi-currency billing and recurring payments.
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "\U0001F4B3",
+        "requires": { "bins": ["node"], "env": ["STRIPE_SECRET_KEY"] },
+        "install":
+          [
+            {
+              "id": "npm",
+              "kind": "node",
+              "package": "cashclaw",
+              "bins": ["cashclaw"],
+              "label": "Install CashClaw via npm"
+            }
+          ]
+      }
+  }
+---
+
+# CashClaw Invoicer
+
+You handle all payment operations for CashClaw. You create invoices, generate
+payment links, track payment status, and send automated reminders. Every dollar
+earned must be tracked accurately. This is the skill that turns delivered work
+into collected revenue.
+
+## Prerequisites
+
+1. **Stripe account** with API access enabled.
+2. **STRIPE_SECRET_KEY** set in environment or `~/.cashclaw/config.json`.
+3. Node.js 18+ installed (for the stripe-ops.js script).
+
+Install the Stripe SDK:
+
+```bash
+npm install stripe
+```
+
+## Invoice Creation
+
+### When to Invoice
+
+- **Pre-payment model**: Create a payment link at ACCEPT stage. Client pays before work begins.
+- **Post-payment model**: Create an invoice at DELIVER stage. Client pays after receiving deliverables.
+- **Recurring services**: Create a Stripe subscription for monthly services (WhatsApp management, social media).
+
+### Invoice Data Structure
+
+```json
+{
+  "mission_id": "MISSION-20260223-001",
+  "client": {
+    "name": "Acme Corp",
+    "email": "billing@acme.com"
+  },
+  "items": [
+    {
+      "description": "SEO Audit - Standard Tier",
+      "quantity": 1,
+      "unit_amount": 2900,
+      "currency": "usd"
+    }
+  ],
+  "due_date": "2026-03-02",
+  "notes": "Thank you for choosing CashClaw!",
+  "metadata": {
+    "mission_id": "MISSION-20260223-001",
+    "service": "seo-audit",
+    "tier": "standard"
+  }
+}
+```
+
+### Using the stripe-ops.js Script
+
+```bash
+# Create a payment link
+node scripts/stripe-ops.js create-link \
+  --amount 2900 \
+  --currency usd \
+  --description "SEO Audit - Standard" \
+  --mission "MISSION-20260223-001"
+
+# Create a full invoice
+node scripts/stripe-ops.js create-invoice \
+  --email "billing@acme.com" \
+  --amount 2900 \
+  --currency usd \
+  --description "SEO Audit - Standard" \
+  --due-days 7
+
+# Check payment status
+node scripts/stripe-ops.js check-status \
+  --invoice "in_1234567890"
+
+# Send payment reminder
+node scripts/stripe-ops.js send-reminder \
+  --invoice "in_1234567890" \
+  --template "gentle"
+```
+
+### Using Stripe API Directly (curl)
+
+If the script is unavailable, use curl with the Stripe API:
+
+```bash
+# Create a customer
+curl https://api.stripe.com/v1/customers \
+  -u "$STRIPE_SECRET_KEY:" \
+  -d "email=client@example.com" \
+  -d "name=Client Name" \
+  -d "metadata[mission_id]=MISSION-20260223-001"
+
+# Create an invoice item
+curl https://api.stripe.com/v1/invoiceitems \
+  -u "$STRIPE_SECRET_KEY:" \
+  -d "customer=cus_xxxxx" \
+  -d "amount=2900" \
+  -d "currency=usd" \
+  -d "description=SEO Audit - Standard Tier"
+
+# Create and send the invoice
+curl https://api.stripe.com/v1/invoices \
+  -u "$STRIPE_SECRET_KEY:" \
+  -d "customer=cus_xxxxx" \
+  -d "collection_method=send_invoice" \
+  -d "days_until_due=7" \
+  -d "auto_advance=true"
+
+# Finalize the invoice
+curl -X POST https://api.stripe.com/v1/invoices/in_xxxxx/finalize \
+  -u "$STRIPE_SECRET_KEY:"
+
+# Send the invoice
+curl -X POST https://api.stripe.com/v1/invoices/in_xxxxx/send \
+  -u "$STRIPE_SECRET_KEY:"
+
+# Create a payment link (one-time)
+curl https://api.stripe.com/v1/payment_links \
+  -u "$STRIPE_SECRET_KEY:" \
+  -d "line_items[0][price_data][currency]=usd" \
+  -d "line_items[0][price_data][product_data][name]=SEO Audit" \
+  -d "line_items[0][price_data][unit_amount]=2900" \
+  -d "line_items[0][quantity]=1"
+
+# Check invoice status
+curl https://api.stripe.com/v1/invoices/in_xxxxx \
+  -u "$STRIPE_SECRET_KEY:"
+
+# List unpaid invoices
+curl "https://api.stripe.com/v1/invoices?status=open&limit=100" \
+  -u "$STRIPE_SECRET_KEY:"
+```
+
+## Payment Reminder Flow
+
+Automated reminders follow this exact schedule:
+
+### Day 0: Invoice Sent
+
+```
+Subject: Invoice #{number} from {Business Name}
+
+Hi {name},
+
+Please find your invoice for {service} attached.
+
+Amount: {currency} {amount}
+Due Date: {due_date}
+
+Pay now: {payment_link}
+
+Thank you for your business!
+
+Best,
+{Business Name}
+```
+
+### Day 3: Gentle Reminder
+
+Only send if invoice is still unpaid.
+
+```
+Subject: Friendly reminder: Invoice #{number}
+
+Hi {name},
+
+Just a quick reminder that invoice #{number} for {amount} is
+due on {due_date}.
+
+You can pay securely here: {payment_link}
+
+If you have already paid, please disregard this message.
+
+Thanks!
+{Business Name}
+```
+
+### Day 7: Follow-up
+
+```
+Subject: Invoice #{number} - Payment due
+
+Hi {name},
+
+Your invoice #{number} for {amount} is now past due.
+
+We would appreciate it if you could process payment at your
+earliest convenience: {payment_link}
+
+If there is an issue with the invoice or you need to discuss
+payment arrangements, please let us know.
+
+Best regards,
+{Business Name}
+```
+
+### Day 14: Final Notice
+
+```
+Subject: Final notice: Invoice #{number} overdue
+
+Hi {name},
+
+This is our final reminder regarding invoice #{number} for
+{amount}, which is now 14 days past due.
+
+Please process payment immediately: {payment_link}
+
+If we do not receive payment or hear from you within 48 hours,
+we may need to pause any ongoing services.
+
+If there are any issues, please reach out so we can work
+something out.
+
+Regards,
+{Business Name}
+```
+
+### Reminder Rules
+
+1. Never send more than 1 reminder per day.
+2. Stop reminders immediately once payment is received.
+3. If client responds to a reminder, pause automation and handle personally.
+4. After Day 14 with no response, escalate to operator -- do not send more reminders.
+5. Track all reminder events in `~/.cashclaw/ledger.jsonl`.
+
+## Multi-Currency Support
+
+Supported currencies and their Stripe codes:
+
+| Currency | Code | Smallest Unit | Example |
+|----------|------|---------------|---------|
+| US Dollar | usd | cents | $29.00 = 2900 |
+| Euro | eur | cents | 29.00 EUR = 2900 |
+| British Pound | gbp | pence | 29.00 GBP = 2900 |
+| Turkish Lira | try | kurus | 29.00 TRY = 2900 |
+| Canadian Dollar | cad | cents | $29.00 CAD = 2900 |
+| Australian Dollar | aud | cents | $29.00 AUD = 2900 |
+
+**Important**: Stripe uses the smallest currency unit (cents, pence, etc.).
+Always multiply the display amount by 100 before sending to Stripe.
+
+### Currency Detection
+
+- Default to USD unless client specifies otherwise.
+- Detect from client's location or previous invoices.
+- Always confirm currency with client before invoicing.
+
+## Payment Tracking
+
+### Ledger Entry Format
+
+Every payment event is logged to `~/.cashclaw/ledger.jsonl`:
+
+```json
+{"ts":"2026-02-23T12:00:00Z","event":"invoice_created","mission_id":"MISSION-20260223-001","invoice_id":"in_xxx","amount":2900,"currency":"usd"}
+{"ts":"2026-02-23T12:01:00Z","event":"invoice_sent","mission_id":"MISSION-20260223-001","invoice_id":"in_xxx"}
+{"ts":"2026-02-23T14:30:00Z","event":"payment_received","mission_id":"MISSION-20260223-001","invoice_id":"in_xxx","amount":2900,"currency":"usd","payment_id":"pi_xxx"}
+```
+
+### Dashboard Update
+
+After every payment event, update `~/.cashclaw/dashboard.json`:
+
+```json
+{
+  "pending_payments": [
+    {
+      "invoice_id": "in_xxx",
+      "mission_id": "MISSION-20260223-001",
+      "amount": 2900,
+      "currency": "usd",
+      "status": "open",
+      "due_date": "2026-03-02",
+      "reminder_stage": 0
+    }
+  ],
+  "recent_payments": [
+    {
+      "invoice_id": "in_yyy",
+      "amount": 900,
+      "currency": "usd",
+      "paid_at": "2026-02-22T10:00:00Z"
+    }
+  ]
+}
+```
+
+## Refund Handling
+
+If a client requests a refund:
+
+1. Verify the original payment in Stripe.
+2. Determine refund type:
+   - **Full refund**: Client unhappy with deliverable. Process immediately.
+   - **Partial refund**: Scope reduced or partial delivery. Calculate pro-rata.
+3. Process via Stripe:
+
+```bash
+# Full refund
+curl https://api.stripe.com/v1/refunds \
+  -u "$STRIPE_SECRET_KEY:" \
+  -d "payment_intent=pi_xxxxx"
+
+# Partial refund
+curl https://api.stripe.com/v1/refunds \
+  -u "$STRIPE_SECRET_KEY:" \
+  -d "payment_intent=pi_xxxxx" \
+  -d "amount=1500"
+```
+
+4. Log the refund event in the ledger.
+5. Update mission status to `refunded`.
+6. Send confirmation to client.
+
+## Recurring Billing
+
+For monthly services (WhatsApp Manager, Social Media):
+
+```bash
+# Create a product
+curl https://api.stripe.com/v1/products \
+  -u "$STRIPE_SECRET_KEY:" \
+  -d "name=Social Media Management - Monthly Full" \
+  -d "metadata[service]=social-media" \
+  -d "metadata[tier]=monthly-full"
+
+# Create a recurring price
+curl https://api.stripe.com/v1/prices \
+  -u "$STRIPE_SECRET_KEY:" \
+  -d "product=prod_xxxxx" \
+  -d "unit_amount=4900" \
+  -d "currency=usd" \
+  -d "recurring[interval]=month"
+
+# Create a subscription
+curl https://api.stripe.com/v1/subscriptions \
+  -u "$STRIPE_SECRET_KEY:" \
+  -d "customer=cus_xxxxx" \
+  -d "items[0][price]=price_xxxxx"
+```
+
+## Error Handling
+
+| Stripe Error | Meaning | Action |
+|-------------|---------|--------|
+| `card_declined` | Card was declined | Ask client for alternative payment method |
+| `expired_card` | Card has expired | Notify client to update card |
+| `incorrect_cvc` | Wrong CVC | Ask client to retry with correct CVC |
+| `processing_error` | Stripe processing issue | Retry after 5 minutes |
+| `rate_limit` | Too many API calls | Wait 60 seconds, then retry |
+
+Never expose raw Stripe error messages to clients. Translate them to
+human-friendly messages.
+
+## Example Commands
+
+```bash
+# Create and send an invoice
+cashclaw invoice --client "billing@acme.com" --amount 29 --service "SEO Audit" --due 7
+
+# Check all unpaid invoices
+cashclaw invoice --list --status unpaid
+
+# Send reminders for overdue invoices
+cashclaw invoice --remind --overdue
+
+# Process a refund
+cashclaw invoice --refund --invoice "in_xxxxx" --amount 29
+```