claude-home/productivity/n8n/workflows/QUICK-START.md

# Ko-fi → Paper Dynasty Quick Start Guide

Get the Ko-fi integration running in 30 minutes.

## Prerequisites Checklist

Before you start, gather these items:

- [ ] Ko-fi verification token (from Ko-fi dashboard)
- [ ] Paper Dynasty API key (production)
- [ ] Discord webhook URL for notifications
- [ ] List of Ko-fi product codes you'll sell
- [ ] Access to n8n at https://n8n.manticorum.com

## Setup Steps

### Step 1: Get Ko-fi Verification Token (2 minutes)

1. Login to Ko-fi: https://ko-fi.com/
2. Navigate to: Settings → API → Webhooks → Advanced (dropdown)
3. Copy the **Verification Token** (looks like: `8c2a3835-4544-4f27-a53a-adfd1fcc5664`)
4. Save it securely - you'll add it to n8n next

### Step 2: Create Discord Webhook (2 minutes)

1. Open Discord channel where you want notifications
2. Channel Settings → Integrations → Webhooks → New Webhook
3. Name it: "Ko-fi Paper Dynasty"
4. Copy webhook URL (looks like: `https://discord.com/api/webhooks/...`)
5. Save URL - you'll add it to n8n next

### Step 3: Configure n8n Credentials (5 minutes)

Login to n8n and create three credentials:

**Credential 1: Ko-fi Verification Token**
1. n8n → Settings → Credentials → Add Credential
2. Search for "Generic Credential"
3. Name: `Ko-fi Verification Token`
4. Add field: `verification_token`
5. Value: `[paste your Ko-fi token here]`
6. Save

**Credential 2: Paper Dynasty API**
1. Add Credential → Search for "Header Auth"
2. Name: `Paper Dynasty API`
3. Header Name: `Authorization`
4. Value: `Bearer [your-pd-api-key]`
5. Save

**Credential 3: Discord Webhook**
1. Add Credential → Search for "Discord Webhook"
2. Name: `Discord Ko-fi Notifications`
3. Webhook URL: `[paste Discord webhook URL]`
4. Save

### Step 4: Create Product Mapping (5 minutes)

1. n8n → Settings → Variables → Add Variable
2. Variable Name: `KOFI_PRODUCT_MAP`
3. Value: Copy and customize this JSON:

```json
{
  "pack-standard-5": {
    "name": "5-Pack Standard",
    "pack_type_id": 1,
    "quantity": 5,
    "pack_cardset_id": null
  },
  "pack-premium-10": {
    "name": "10-Pack Premium",
    "pack_type_id": 3,
    "quantity": 10,
    "pack_cardset_id": null
  }
}
```

**Important:** Replace `pack-standard-5` and `pack-premium-10` with your actual Ko-fi product codes.

4. Save variable

### Step 5: Import Workflow (10 minutes)

**Option A: Manual Creation**

Follow the detailed node-by-node instructions in `kofi-paper-dynasty.md`

**Option B: JSON Import (if workflow JSON provided)**

1. n8n → Workflows → Add Workflow → Import from File
2. Select workflow JSON file
3. Review imported nodes
4. Update credential references if needed
5. Activate workflow

**Key Nodes to Verify:**
- Webhook path: `/kofi-paperdy` (use `/webhook-test/kofi-paperdy` initially)
- Token validation references correct credential
- Product mapping loads from variable
- API endpoints correct (`https://pd.manticorum.com/api/v2/`)
- Discord notifications reference correct credential

### Step 6: Test the Workflow (5 minutes)

**Quick Test with cURL:**

```bash
# Replace YOUR_KOFI_TOKEN_HERE with your actual token
curl -X POST 'https://n8n.manticorum.com/webhook-test/kofi-paperdy' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'data={
    "verification_token": "YOUR_KOFI_TOKEN_HERE",
    "message_id": "quick-test-001",
    "timestamp": "2025-11-13T12:00:00Z",
    "type": "Shop Order",
    "from_name": "Test User",
    "message": "Team: SKB",
    "amount": "5.00",
    "email": "[email protected]",
    "currency": "USD",
    "kofi_transaction_id": "quick-test-001",
    "shop_items": [
      {
        "direct_link_code": "pack-standard-5",
        "variation_name": "5-Pack Standard",
        "quantity": 1
      }
    ],
    "discord_userid": null
  }'
```

**Expected Results:**
- ✅ n8n shows successful execution
- ✅ Discord notification received
- ✅ If using real API, 5 packs granted to team SKB

### Step 7: Configure Ko-fi Webhook (3 minutes)

1. Ko-fi → Settings → API → Webhooks
2. **Webhook URL:** `https://n8n.manticorum.com/webhook-test/kofi-paperdy` (test first!)
3. Save
4. Click "Test Webhook" button
5. Verify n8n receives webhook and processes successfully
6. Check Discord for test notification

### Step 8: Go Live (2 minutes)

Once testing is successful:

1. **Update workflow webhook path:**
   - n8n → Edit Workflow → Webhook node
   - Change path from `webhook-test/kofi-paperdy` to `webhook/kofi-paperdy`
   - Save and activate workflow

2. **Update Ko-fi webhook URL:**
   - Ko-fi → Settings → API → Webhooks
   - Change URL to: `https://n8n.manticorum.com/webhook/kofi-paperdy`
   - Save

3. **Monitor first transactions:**
   - Watch Discord channel closely
   - Review n8n execution logs
   - Verify packs granted correctly in Paper Dynasty

Done! Your Ko-fi integration is now live.

---

## Post-Setup Tasks

### Create Ko-fi Products

For each pack type you want to sell:

1. Ko-fi → Shop → Add Product
2. **Product Name:** "5-Pack Standard Bundle"
3. **Price:** $5.00
4. **Description:** "Five standard Paper Dynasty packs"
5. **Advanced Settings → Product Code:** `pack-standard-5`
   - ⚠️ This MUST match your product mapping!
6. Add product image
7. Publish product

**Repeat for each pack type** (premium, team choice, etc.)

### Document Your Product Codes

Keep a master list of all Ko-fi product codes and their mappings:

| Ko-fi Code | Pack Type | Quantity | Price | PD pack_type_id |
|------------|-----------|----------|-------|-----------------|
| pack-standard-5 | Standard | 5 | $5.00 | 1 |
| pack-standard-10 | Standard | 10 | $9.00 | 1 |
| pack-premium-5 | Premium | 5 | $10.00 | 3 |
| pack-premium-10 | Premium | 10 | $18.00 | 3 |
| pack-team-choice | Team Choice | 1 | $3.00 | 8 |

Update this when adding new products!

### Set Up Monitoring

**Create a monitoring checklist:**
- [ ] Check Discord notifications daily
- [ ] Review n8n execution logs weekly
- [ ] Verify pack distribution accuracy weekly
- [ ] Update product mapping when adding Ko-fi products
- [ ] Test disaster recovery monthly

### Backup n8n

**Create weekly backup:**
```bash
ssh root@10.10.0.210 "
cd /opt/n8n && \
docker compose exec -T postgres pg_dump -U n8n n8n > \
/root/n8n-backup-\$(date +%Y%m%d-%H%M%S).sql
"

# Download backup
scp root@10.10.0.210:/root/n8n-backup-*.sql ~/backups/n8n/
```

---

## Troubleshooting

### Webhook Not Receiving Data

**Check:**
```bash
# Test webhook endpoint
curl -I https://n8n.manticorum.com/webhook-test/kofi-paperdy

# Should return: 200 OK or 400 Bad Request (not 404)
```

**Fix:**
- Ensure workflow is Active (toggle in n8n UI)
- Verify webhook path matches Ko-fi configuration
- Check n8n logs: `ssh root@10.10.0.210 "cd /opt/n8n && docker compose logs -f n8n"`

### Token Validation Failing

**Check:**
- Token in n8n credential matches Ko-fi exactly (no spaces!)
- Credential name in IF node: `{{ $credentials.kofiVerificationToken.verification_token }}`

**Fix:**
- Re-copy token from Ko-fi
- Update n8n credential
- Test again

### Team Not Found

**Check:**
- User has discord_userid linked in Paper Dynasty
- OR user included team abbrev in message (e.g., "Team: SKB")
- Team abbreviation exists in PD database

**Fix:**
- Manual review Discord notification will be sent
- Admin grants packs manually using transaction ID

### Packs Not Granted

**Check:**
- n8n execution log shows 200 OK from PD API
- Product code exists in `KOFI_PRODUCT_MAP` variable
- pack_type_id is valid

**Verify in Paper Dynasty:**
```python
from api_client import PaperDynastyAPI
api = PaperDynastyAPI(environment='prod')
api.list_packs(team_id=69, opened=False, limit=20)
```

---

## Next Steps

Now that your integration is running:

1. **Read full documentation:** `kofi-paper-dynasty.md`
2. **Review test scenarios:** `kofi-testing-guide.md`
3. **Customize product mapping:** Add more pack types
4. **Set up monitoring alerts:** Create health check workflow
5. **Document your process:** Add notes for future reference

---

## Support Resources

**Documentation:**
- Full Setup: `kofi-paper-dynasty.md`
- Testing Guide: `kofi-testing-guide.md`
- Product Mapping: `kofi-product-mapping-template.json`
- n8n Context: `/productivity/n8n/CONTEXT.md`

**External Resources:**
- Ko-fi Webhook Docs: https://help.ko-fi.com/hc/en-us/articles/360004162298
- n8n Documentation: https://docs.n8n.io/
- Paper Dynasty API: See `/home/cal/.claude/skills/paper-dynasty/SKILL.md`

**Need Help?**
- Review n8n execution logs for detailed error messages
- Check Discord notifications for manual review requests
- Test with cURL to isolate issues
- Consult troubleshooting guide in main documentation

---

## Change Log

### 2025-11-13 - Initial Version
- Created quick start guide
- Defined 30-minute setup process
- Added troubleshooting quick reference
- Included post-setup tasks and monitoring