dubs-server 1.0.0

package/postman/QUICKSTART.md

@@ -0,0 +1,118 @@
+# 🎮 Dubs API - Quick Start
+
+## What Changed (Production-Ready Now!)
+
+✅ **UUIDs instead of integers** - Professional game IDs  
+✅ **Address-based winners only** - No more confusing indices  
+✅ **Multi-game support** - Run unlimited games simultaneously  
+✅ **Production endpoints** - Real wallet signing support  
+✅ **Demo endpoints** - Easy testing with server-managed wallets  
+
+---
+
+## Import Postman Collection
+
+File: `Dubs-API.postman_collection.json`
+
+You'll see **3 folders**:
+1. **Demo Mode** - Server signs (for testing)
+2. **Production Mode** - Client signs (for real users)
+3. **Utilities** - Helper endpoints
+
+---
+
+## Demo Mode Workflow (Testing)
+
+### Step 1: Create Game
+Request: **"3. Create Game"**
+
+Leave gameId blank - it auto-generates a UUID!
+
+**Response:**
+```json
+{
+  "success": true,
+  "gameId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  ← Save this!
+  "message": "Game created, operator: jelli",
+  "gameAddress": "..."
+}
+```
+
+### Step 2: Copy the UUID
+
+**IMPORTANT:** Copy that UUID! You'll use it for everything else.
+
+### Step 3: View Game
+
+Request: **"4. View Game"**
+
+Replace `PASTE_GAME_UUID_HERE` in URL with your UUID.
+
+**Response shows player addresses:**
+```json
+{
+  "game": {
+    "players": [
+      "GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc",  ← Alice
+      "AuskVDhGKzZ9xWJaY5RKWzBZzeGuEYZ6mZXCDeTQCJcw"   ← Bob
+    ]
+  }
+}
+```
+
+### Step 4: Alice & Bob Join
+
+Requests: **"5. Alice Joins"** and **"6. Bob Joins"**
+
+Replace `PASTE_GAME_UUID_HERE` with your UUID in both.
+
+### Step 5: Distribute Using Addresses
+
+Request: **"7. Distribute - Using Addresses"**
+
+1. Replace `PASTE_GAME_UUID_HERE` with your UUID
+2. Copy Alice & Bob's addresses from Step 3
+3. Paste into `winners` array
+
+**Result:**
+- Jelli gets 10% operator fee 💰
+- Alice & Bob split the rest 50/50
+
+### Step 6: Verify Jelli Got Paid
+
+Request: **"8. Check Jelli Got Paid"**
+
+See Jelli's balance increased!
+
+---
+
+## Production Mode (Real Wallets)
+
+For integrating with Phantom/Solflare wallets:
+
+1. **Build Transaction** - Server creates unsigned transaction
+2. **Sign in Wallet** - User signs with Phantom
+3. **Submit** - Send signed transaction to server
+
+---
+
+## Key Differences
+
+| Feature | Demo Mode | Production Mode |
+|---------|-----------|-----------------|
+| Game ID | UUID (auto) | UUID (specify) |
+| Wallets | Server-managed | User's wallet |
+| Signing | Server signs | User signs |
+| Winners | Addresses | Addresses |
+
+---
+
+## Try It Now!
+
+1. Run requests 1-8 in **Demo Mode** folder
+2. Use actual UUIDs (copy/paste from responses)
+3. Use actual addresses for winners
+4. Watch it work perfectly! 🎉
+
+**No more technical debt!** Clean, professional API! 🚀
+

package/postman/QUICK_REFERENCE.md

@@ -0,0 +1,246 @@
+# 🎮 Dubs API - Quick Reference
+
+## 🌐 **Base URL (Devnet)**
+```
+https://dubs-server-dev-55d1fba09a97.herokuapp.com
+```
+
+---
+
+## 📋 **All Endpoints**
+
+### **Game Info**
+```
+GET /api/v1/prod/game/:gameId
+```
+
+### **Create Game**
+```
+POST /api/v1/prod/transaction/build/create
+
+Body:
+{
+  "creatorAddress": "string",
+  "buyIn": number (SOL),
+  "maxPlayers": number (2-20),
+  "operatorFee": number (0-100),
+  "votingEnabled": boolean,
+  "gameMode": number (0=Manual, 1=Democratic, 2=Referee), ← NEW!
+  "refereeAddress": string (optional, required for Referee mode), ← NEW!
+  "refereeCommission": number (0-100, typical 10-20%) ← NEW!
+}
+
+Game Modes:
+0 = Manual (Creator chooses winner)
+1 = Democratic (Players vote, majority rules)
+2 = Referee (Expert judge decides, earns commission)
+```
+
+### **Join Game**
+```
+POST /api/v1/prod/transaction/build/join
+
+Body:
+{
+  "playerAddress": "string",
+  "gameId": "uuid"
+}
+```
+
+### **Cast Vote** 🗳️ NEW!
+```
+POST /api/v1/prod/transaction/build/cast-vote
+
+Body:
+{
+  "voterAddress": "string",
+  "gameId": "uuid",
+  "votedFor": "string" (player address)
+}
+```
+
+### **Distribute by Vote** 🗳️ NEW!
+```
+POST /api/v1/prod/transaction/build/distribute-by-vote
+
+Body:
+{
+  "creatorAddress": "string",
+  "gameId": "uuid"
+}
+
+Returns:
+{
+  "transaction": "base64",
+  "winners": ["address1", "address2"],
+  "voteCounts": {
+    "address1": 2,
+    "address2": 1
+  }
+}
+```
+
+### **Distribute Manually**
+```
+POST /api/v1/prod/transaction/build/distribute
+
+Body:
+{
+  "creatorAddress": "string",
+  "gameId": "uuid",
+  "winners": ["address1", "address2"]
+}
+```
+
+### **Submit Transaction**
+```
+POST /api/v1/prod/transaction/submit
+
+Body:
+{
+  "signedTransaction": "base64"
+}
+```
+
+---
+
+## 🎯 **Response Format**
+
+### **Game Info Response:**
+```json
+{
+  "exists": true,
+  "game": {
+    "gameId": 12345,
+    "authority": "CreatorAddr",
+    "buyIn": 0.5,
+    "maxPlayers": 3,
+    "players": ["P1", "P2", "P3"],
+    "totalPot": 1.5,
+    "isActive": true,
+    "votes": [
+      {"voter": "P1", "votedFor": "P2"},
+      {"voter": "P2", "votedFor": "P2"}
+    ],
+    "votingEnabled": true
+  },
+  "calculated": {
+    "operatorFeeAmount": "0.1500",
+    "prizePool": "1.3500"
+  }
+}
+```
+
+---
+
+## 🗳️ **Voting Cheat Sheet**
+
+### **Majority Formula:**
+```
+Needed Votes = (Total Players / 2) + 1
+```
+
+### **Examples:**
+```
+2 players → Need 2 votes
+3 players → Need 2 votes
+4 players → Need 3 votes
+5 players → Need 3 votes
+```
+
+### **Voting States:**
+```
+0 votes    → "Not started"
+< majority → "In progress"
+≥ majority → "Can distribute!"
+```
+
+---
+
+## ⚡ **Quick Tests**
+
+### **Test 1: Create & Join**
+```bash
+curl -X POST {{baseUrl}}/api/v1/prod/transaction/build/create \
+  -H "Content-Type: application/json" \
+  -d '{"creatorAddress":"YOUR_ADDRESS","buyIn":0.5,"maxPlayers":2,"operatorFee":10,"votingEnabled":true}'
+```
+
+### **Test 2: Cast Vote**
+```bash
+curl -X POST {{baseUrl}}/api/v1/prod/transaction/build/cast-vote \
+  -H "Content-Type: application/json" \
+  -d '{"voterAddress":"YOUR_ADDRESS","gameId":"GAME_UUID","votedFor":"PLAYER_ADDRESS"}'
+```
+
+### **Test 3: Check Game**
+```bash
+curl {{baseUrl}}/api/v1/prod/game/GAME_UUID
+```
+
+---
+
+## 🎮 **Postman Collections**
+
+### **Latest (With Voting):**
+```
+postman/Dubs-API-v1-With-Voting.postman_collection.json
+```
+
+**Includes:**
+- ✅ All production endpoints
+- ✅ Democratic voting workflow
+- ✅ Manual distribution workflow
+- ✅ Demo/test endpoints
+- ✅ Auto-save game IDs
+- ✅ Example responses
+
+### **Guide:**
+```
+postman/VOTING_API_GUIDE.md
+```
+
+---
+
+## 📊 **Status Codes**
+
+```
+200 - Success
+400 - Bad Request (invalid parameters)
+404 - Game Not Found
+500 - Server Error (check Heroku logs)
+```
+
+---
+
+## 🔧 **Environment Setup**
+
+### **Postman Variables:**
+```
+baseUrl: https://dubs-server-dev-55d1fba09a97.herokuapp.com
+walletAddress: YOUR_SOLANA_ADDRESS
+gameId: (auto-saved from create response)
+```
+
+---
+
+## 🚀 **Live Testing**
+
+1. Import Postman collection
+2. Set `walletAddress` variable
+3. Run "Democratic Game Flow" folder
+4. Sign transactions with Phantom
+5. Submit via `/transaction/submit`
+6. Watch democracy in action! 🗳️
+
+---
+
+**Need Help?**
+- Full docs: `README.md`
+- Voting guide: `postman/VOTING_API_GUIDE.md`
+- Heroku logs: `heroku logs --tail -a dubs-server-dev`
+
+---
+
+**Built with ❤️ on Solana** 🎮🗳️⛓️
+

package/postman/README.md

@@ -0,0 +1,71 @@
+# 🎮 Dubs API - Postman Collection
+
+## Import
+
+1. Open Postman
+2. Click **Import**
+3. Select: `Dubs-API.postman_collection.json`
+
+## Run in Order
+
+### Quick Test Flow:
+
+1. **Health Check** - Verify server
+2. **Create Game #1** - Jelli as operator
+3. **Alice Joins Game #1**
+4. **Bob Joins Game #1**
+5. **Get Game Info** - See the pot!
+6. **Distribute - Two Winners** - Alice & Bob split, Jelli gets fee!
+7. **List All Players** - See Jelli got paid! 💰
+
+---
+
+## Multiple Games Example:
+
+You can run multiple games at once!
+
+1. **Create Game #1** - Mario Kart (gameId: 1)
+2. **Create Game #2** - Golf (gameId: 2)
+3. **Alice joins Game #1**
+4. **Bob joins Game #2**
+5. Both games run independently!
+
+---
+
+## Key Parameters:
+
+### Create Game:
+```json
+{
+  "gameId": 1,              // Unique ID (or leave blank for auto)
+  "player": "creator",       // Who creates
+  "buyIn": 0.5,             // SOL amount
+  "maxPlayers": 4,          // Max players
+  "operatorFee": 10,        // Percentage (0-100)
+  "operatorPlayer": "jelli" // Who gets fees
+}
+```
+
+### Join Game:
+```json
+{
+  "player": "alice",  // Who joins
+  "gameId": 1         // Which game
+}
+```
+
+### Distribute:
+```json
+{
+  "gameId": 1,
+  "player": "creator",
+  "winners": [0, 1]   // Player indices (0=first, 1=second, etc.)
+}
+```
+
+---
+
+## That's It!
+
+Just click through the requests! ✨
+