zerocarbon-quickstart 1.0.0

package/DEPLOYMENT_GUIDE.md

@@ -0,0 +1,437 @@
+# Deployment Guide - Developer Love Demo
+
+## 🎯 Goal
+Deploy a "Hello World" carbon emissions demo that YC partners can test in under 5 minutes.
+
+---
+
+## 📋 Pre-Deployment Checklist
+
+### 1. Update Production API URLs
+Currently using `https://api.zerocarbon.codes` - ensure this points to your **production API**.
+
+- [ ] Update API base URL in `index.js`
+- [ ] Update API base URL in `quickstart.py`
+- [ ] Update API base URL in `web-demo.html`
+- [ ] Test all endpoints return valid data
+
+### 2. Enable Public API Testing
+For the demo to work, your API must:
+
+- [ ] Allow unauthenticated requests to `/v1/emissions/calculate`
+- [ ] Allow unauthenticated requests to `/v1/calculate/flight`
+- [ ] Allow unauthenticated requests to `/v1/calculate/fuel`
+- [ ] Set rate limit: 1000 requests/day per IP (generous for testing)
+- [ ] Return proper CORS headers for web demo
+
+**Add to your API routes:**
+```typescript
+// Middleware for public endpoints
+export const allowPublicTesting = (req: Request, res: Response, next: NextFunction) => {
+  // Skip auth for testing endpoints
+  if (req.path.startsWith('/v1/calculate') || req.path === '/v1/emissions/calculate') {
+    const ip = req.ip || req.headers['x-forwarded-for'];
+    
+    // Check rate limit (1000/day per IP)
+    if (isRateLimited(ip)) {
+      return res.status(429).json({ 
+        error: 'Rate limit exceeded. Get free API key: https://app.zerocarbon.codes/signup' 
+      });
+    }
+    
+    return next();
+  }
+  
+  // Regular auth for other endpoints
+  return verifyAuth(req, res, next);
+};
+```
+
+### 3. Set Up Monitoring
+Track how many people test your demo:
+
+- [ ] Add analytics to quickstart.zerocarbon.codes
+- [ ] Log IP addresses hitting public endpoints
+- [ ] Set up alerts for >100 tests/day (viral signal)
+- [ ] Track conversion: demo → signup → paid
+
+---
+
+## 🚀 Deployment Steps
+
+### Step 1: Deploy Web Demo
+
+**Option A: Vercel (Fastest)**
+```bash
+cd quickstart
+npx vercel --prod
+
+# Set custom domain
+vercel domains add quickstart.zerocarbon.codes
+```
+
+**Option B: Netlify**
+```bash
+cd quickstart
+netlify deploy --prod --dir=.
+
+# Add redirect rules in netlify.toml
+```
+
+**Option C: CloudFlare Pages**
+```bash
+# Via dashboard: New Project → Connect Git → Deploy
+# Set build command: none
+# Set output directory: quickstart/
+```
+
+**Test it:**
+```bash
+curl https://quickstart.zerocarbon.codes/web-demo.html
+```
+
+### Step 2: Publish NPM Package
+
+```bash
+cd quickstart
+
+# Login to NPM
+npm login
+
+# Update package.json with unique name
+# Change "zerocarbon-quickstart" to "your-company-quickstart" if taken
+
+# Publish
+npm publish --access public
+
+# Test installation
+npm install -g zerocarbon-quickstart
+npx zerocarbon-quickstart
+```
+
+**Important:** Your package name must be unique on NPM. If `zerocarbon-quickstart` is taken, use:
+- `@zerocarbon/quickstart`
+- `zerocarbon-api-demo`
+- `carbon-quickstart`
+
+### Step 3: Deploy to Replit
+
+1. Go to [Replit.com](https://replit.com)
+2. Click "Create Repl" → "Import from GitHub"
+3. Enter your GitHub repo URL (or upload files directly)
+4. Make repl public
+5. Get shareable link: `https://replit.com/@yourusername/quickstart`
+
+**Configure Replit:**
+- Set run command: `node index.js`
+- Set language: Node.js
+- Enable "Always on" (optional, costs credits)
+
+### Step 4: Deploy to CodeSandbox
+
+1. Go to [CodeSandbox.io](https://codesandbox.io)
+2. Click "Create Sandbox" → "Import from GitHub"
+3. Enter your repo URL
+4. Make sandbox public
+5. Get shareable link: `https://codesandbox.io/s/zerocarbon-quickstart`
+
+**Configure CodeSandbox:**
+- Set main file: `index.js`
+- Enable "Hot Reloading"
+
+### Step 5: Create GitHub Repository
+
+```bash
+cd quickstart
+git init
+git add .
+git commit -m "Initial commit: ZeroCarbon API Quickstart"
+
+# Create repo on GitHub, then:
+git remote add origin https://github.com/zerocarbon/quickstart.git
+git push -u origin main
+
+# Add README badges
+# Add demo GIF/video
+# Add clear instructions
+```
+
+**Repository Structure:**
+```
+quickstart/
+├── README.md              # Main documentation
+├── YC_APPLICATION_GUIDE.md # YC-specific guide
+├── DEPLOYMENT_GUIDE.md    # This file
+├── index.js               # Node.js demo
+├── package.json           
+├── quickstart.py          # Python demo
+├── curl-examples.sh       # cURL examples
+├── web-demo.html          # Interactive web demo
+├── .replitrc              # Replit config
+└── .codesandbox/
+    └── tasks.json         # CodeSandbox config
+```
+
+---
+
+## 🧪 Testing Checklist
+
+Before announcing:
+
+### Test on Multiple Platforms
+- [ ] **Mac Terminal:** `npx zerocarbon-quickstart` works
+- [ ] **Windows PowerShell:** Works without errors
+- [ ] **Linux Terminal:** Works
+- [ ] **Replit:** Opens and runs immediately
+- [ ] **CodeSandbox:** Opens and runs  
+- [ ] **Web browser:** https://quickstart.zerocarbon.codes loads
+
+### Test API Endpoints
+- [ ] Electricity calculation returns valid data
+- [ ] Flight calculation works (SFO → JFK)
+- [ ] Vehicle calculation works
+- [ ] Natural gas calculation works
+- [ ] All return proper JSON format
+- [ ] Error messages are helpful
+
+### Test Different Networks
+- [ ] Test from home WiFi
+- [ ] Test from mobile data
+- [ ] Test from VPN (simulates YC office)
+- [ ] Test from different countries (IP)
+
+### Performance
+- [ ] Demo loads in <2 seconds
+- [ ] API responds in <500ms
+- [ ] No rate limit errors during normal use
+- [ ] Handles 100 concurrent users
+
+---
+
+## 🎯 YC Application Integration
+
+### 1. Update Application Text
+
+**In "How do you know people want your product?":**
+```
+We're the fastest carbon API to integrate. Try it yourself:
+
+1. Run `npx zerocarbon-quickstart` in your terminal
+2. Or visit: https://quickstart.zerocarbon.codes
+3. Or open: https://replit.com/@zerocarbon/quickstart
+
+Developers get their first emissions calculation in under 5 minutes. 
+50 beta users integrated in 18 minutes average (vs. 2-3 hours for competitors).
+
+The best part? This demo makes the same API calls our paying customers use. 
+It's not a fake demo—it's our production API with zero friction.
+```
+
+### 2. Add to "Product Demo" Section
+
+**Primary CTA:**
+> "Try our API live: https://quickstart.zerocarbon.codes"
+
+**Secondary CTA:**
+> "Zero installation: `npx zerocarbon-quickstart`"
+
+### 3. For Video Interview
+
+Have this ready to share screen:
+1. Open terminal
+2. Run `npx zerocarbon-quickstart`
+3. Show results in real-time
+4. Say: "This is what every developer experiences. Zero friction."
+
+---
+
+## 📊 Post-Launch Monitoring
+
+### Metrics to Track
+
+**Usage Metrics:**
+- NPM downloads per day
+- Web demo visits per day
+- Replit forks
+- CodeSandbox opens
+- API calls from demo endpoints
+
+**Conversion Metrics:**
+- Demo → API signup %
+- Demo → Paid customer %
+- Time from demo to first paid API call
+- Demo → YC application submission (if tracking)
+
+**Virality Metrics:**
+- Twitter mentions of demo link
+- GitHub stars on quickstart repo
+- Reddit posts about demo
+- HN upvotes (if posted)
+
+### Set Up Alerts
+
+**High Priority:**
+- >100 demo runs in 24 hours (potential virality)
+- API errors >5% (fix immediately)
+- Demo downtime >1 minute
+
+**Medium Priority:**
+- Rate limit hits (scale or adjust limits)
+- Slow API responses >1s
+- Browser console errors
+
+---
+
+## 🚨 Emergency Procedures
+
+### If Demo Goes Viral
+
+**Scenario:** YC partner tweets demo → 10,000 developers try it
+
+**Actions:**
+1. **Scale API immediately:**
+   - Add Cloudflare in front
+   - Increase rate limits temporarily
+   - Cache common calculations
+   
+2. **Monitor costs:**
+   - Track API compute costs
+   - Set billing alerts
+   - Be ready to add rate limits
+
+3. **Capture leads:**
+   - Add "Want API key?" banner
+   - Offer priority access
+   - Track conversion rate
+
+### If API Goes Down
+
+**Scenario:** Demo fails during YC partner test
+
+**Backup Plan:**
+- Add fallback to mock data in demos
+- Show "API temporarily unavailable" message
+- Capture email for notification when fixed
+
+**Prevention:**
+- Set up uptime monitoring (UptimeRobot, Pingdom)
+- Have backup API endpoint ready
+- Test failover before launch
+
+---
+
+## ✅ Pre-YC Submission Checklist
+
+**24 Hours Before Submission:**
+- [ ] Test demo from 3 different devices
+- [ ] Verify all links work in application
+- [ ] Check API is responding <500ms
+- [ ] Monitor setup and working
+- [ ] Rate limits tested and appropriate
+- [ ] Error messages are helpful, not technical
+- [ ] Demo repo is public
+- [ ] README has clear instructions
+- [ ] Video demo recorded (optional)
+
+**1 Hour Before Submission:**
+- [ ] Test one final time
+- [ ] Check all links in application
+- [ ] Verify analytics are tracking
+- [ ] Monitor dashboard is green
+
+**After Submission:**
+- [ ] Post to Twitter about demo
+- [ ] Post to relevant subreddits (r/programming, r/webdev)
+- [ ] Email to beta users: "We applied to YC, try our demo"
+- [ ] Monitor usage 24/7 for first 48 hours
+
+---
+
+## 📞 Support
+
+If YC partner has issues:
+
+**Email template ready:**
+```
+Subject: ZeroCarbon API Demo - Emergency Support
+
+We're monitoring our demo 24/7 during YC application review.
+
+If you experience any issues:
+1. Email: yc@zerocarbon.codes (monitored every 15 minutes)
+2. Text: [Your Number] (for urgent issues)
+3. Backup demo: https://backup-demo.zerocarbon.codes
+
+Our API uptime: 99.9%
+Average response time: <300ms
+Currently responding to all support requests within 15 minutes.
+
+Thank you for testing our demo!
+```
+
+---
+
+## 🎬 Deployment Timeline
+
+**Week -2:**
+- Build all demos
+- Test thoroughly
+- Get 5 beta users to test
+
+**Week -1:**
+- Deploy to production
+- Set up monitoring
+- Create backups
+
+**Day -3:**
+- Final testing from different locations
+- Write support email templates
+- Set up 24/7 monitoring rotation
+
+**Day -1:**
+- Test one more time
+- Check all links
+- Sleep well
+
+**Day 0 (Submission):**
+- Submit application
+- Monitor demo usage
+- Respond to any issues within 15min
+
+**Days 1-7:**
+- Monitor daily usage
+- Fix any issues immediately
+- Track conversion metrics
+
+---
+
+## 💡 Pro Tips
+
+1. **Make it impossible to fail:**
+   - Add fallback to mock data
+   - Cache common calculations
+   - Have backup API endpoint
+
+2. **Impress with speed:**
+   - Aim for <200ms API responses
+   - Preload common calculations
+   - Use CDN for demo page
+
+3. **Track everything:**
+   - Log every demo run
+   - Track user flow
+   - Know exactly what YC partners see
+
+4. **Be available:**
+   - Check email every 30min
+   - Have phone ready
+   - Monitor demo 24/7
+
+5. **Iterate fast:**
+   - If partners report issues, fix in <1 hour
+   - Deploy fixes immediately
+   - Send follow-up email: "We fixed it"
+
+---
+
+**Ready to deploy?** Start with Step 1 above ⬆️

package/README.md

@@ -0,0 +1,228 @@
+# ZeroCarbon API - 5 Minute Quickstart
+
+Get your first carbon footprint calculation in **under 5 minutes**. No signup required for testing.
+
+## 🚀 One-Line Demos
+
+### Option 1: Node.js (Fastest)
+```bash
+npx zerocarbon-quickstart
+```
+
+### Option 2: Python
+```bash
+pip install zerocarbon && python -m zerocarbon.quickstart
+```
+
+### Option 3: cURL (Zero Installation)
+```bash
+curl -X POST https://api.zerocarbon.codes/v1/emissions/calculate \
+  -H "Content-Type: application/json" \
+  -d '{"source":"electricity","value":1000,"unit":"kWh","country":"US"}'
+```
+
+---
+
+## 🎮 Interactive Demos
+
+### Try on Replit
+[![Run on Replit](https://replit.com/badge/github/zerocarbon/quickstart)](https://replit.com/@zerocarbon/quickstart)
+
+### Try on CodeSandbox
+[![Open in CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/github/zerocarbon/quickstart)
+
+---
+
+## 📖 5-Minute Tutorial
+
+### Step 1: Calculate Emissions (No Auth Needed)
+
+**Node.js**
+```javascript
+const axios = require('axios');
+
+const response = await axios.post('https://api.zerocarbon.codes/v1/emissions/calculate', {
+  source: 'electricity',
+  value: 1000,
+  unit: 'kWh',
+  country: 'US'
+});
+
+console.log(`Your emissions: ${response.data.emissions_kg_co2e} kg CO2e`);
+// Output: Your emissions: 386.5 kg CO2e
+```
+
+**Python**
+```python
+import requests
+
+response = requests.post('https://api.zerocarbon.codes/v1/emissions/calculate', 
+    json={
+        'source': 'electricity',
+        'value': 1000,
+        'unit': 'kWh',
+        'country': 'US'
+    }
+)
+
+print(f"Your emissions: {response.json()['emissions_kg_co2e']} kg CO2e")
+# Output: Your emissions: 386.5 kg CO2e
+```
+
+### Step 2: Calculate Real-World Scenarios
+
+**Flight Emissions**
+```bash
+curl -X POST https://api.zerocarbon.codes/v1/calculate/flight \
+  -H "Content-Type: application/json" \
+  -d '{
+    "from": "SFO",
+    "to": "JFK",
+    "passengers": 1,
+    "class": "economy"
+  }'
+```
+
+**Vehicle Emissions**
+```javascript
+const emissions = await fetch('https://api.zerocarbon.codes/v1/calculate/fuel', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    fuel_type: 'gasoline',
+    distance: 100,
+    unit: 'miles'
+  })
+});
+```
+
+### Step 3: Get Free API Key (30 seconds)
+
+For persistent tracking and dashboard access:
+
+```bash
+# Sign up via API (no email verification needed)
+curl -X POST https://api.zerocarbon.codes/v1/demo-request \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Your Name",
+    "email": "you@company.com",
+    "company": "Your Company"
+  }'
+
+# Instant API key in response:
+# { "api_key": "zc_xxxxx", "dashboard_url": "https://app.zerocarbon.codes" }
+```
+
+---
+
+## 🏗️ Complete Example Apps
+
+### Express.js Server (3 minutes)
+```bash
+git clone https://github.com/zerocarbon/examples
+cd examples/nodejs-express
+npm install && npm start
+```
+
+### Flask API (3 minutes)
+```bash
+git clone https://github.com/zerocarbon/examples
+cd examples/python-flask
+pip install -r requirements.txt && python app.py
+```
+
+### Next.js Dashboard (5 minutes)
+```bash
+git clone https://github.com/zerocarbon/examples
+cd examples/nextjs-dashboard
+npm install && npm run dev
+```
+
+---
+
+## 🎯 Common Use Cases
+
+### Scenario 1: E-commerce Carbon Labels
+```javascript
+// Add carbon footprint to product pages
+const getShippingEmissions = async (weight, distance) => {
+  const res = await fetch('https://api.zerocarbon.codes/v1/calculate/shipping', {
+    method: 'POST',
+    body: JSON.stringify({ weight_kg: weight, distance_km: distance })
+  });
+  return res.json();
+};
+
+// Display: "This shipment produces 2.3 kg CO2e"
+```
+
+### Scenario 2: SaaS Carbon Dashboard
+```javascript
+// Track your infrastructure emissions
+const trackCloudEmissions = async () => {
+  const emissions = await zerocarbon.calculate({
+    source: 'aws_compute',
+    instance_hours: 730,
+    region: 'us-east-1'
+  });
+  
+  await zerocarbon.emissions.save({
+    category: 'cloud_infrastructure',
+    value: emissions.kg_co2e
+  });
+};
+```
+
+### Scenario 3: Travel Booking Carbon Offset
+```javascript
+// Offer carbon offsets at checkout
+const flight = await zerocarbon.calculate.flight({
+  from: 'LAX',
+  to: 'LHR',
+  passengers: 2
+});
+
+const offsetCost = flight.emissions_kg_co2e * 0.015; // $15 per tonne
+// Show: "Add carbon offset for $22.50?"
+```
+
+---
+
+## 📊 What You Get
+
+- **Instant calculations** - No rate limits for testing
+- **200+ emission factors** - Electricity, fuel, flights, shipping, etc.
+- **Global coverage** - Country-specific emission factors
+- **GHG Protocol compliant** - Scope 1, 2, 3 classifications
+- **Auto-generated reports** - BRSR, SEC, TCFD, CDP formats
+
+---
+
+## 💡 Why Developers Love It
+
+✅ **No authentication** for quick testing  
+✅ **RESTful API** with predictable endpoints  
+✅ **JSON in, JSON out** - No XML, no SOAP  
+✅ **Native SDKs** for Node.js, Python, Go, Ruby  
+✅ **Webhook support** for async calculations  
+✅ **OpenAPI spec** for auto-generating clients  
+
+---
+
+## 🔗 Next Steps
+
+- [Full API Documentation](https://docs.zerocarbon.codes)
+- [Interactive API Explorer](https://api.zerocarbon.codes/playground)
+- [Example Applications](https://github.com/zerocarbon/examples)
+- [Get Production API Key](https://app.zerocarbon.codes/signup)
+
+---
+
+## 💬 Questions?
+
+- Discord: [discord.gg/zerocarbon](https://discord.gg/zerocarbon)
+- Email: developers@zerocarbon.codes
+- Docs: [docs.zerocarbon.codes](https://docs.zerocarbon.codes)
+
+**Try it now:** `npx zerocarbon-quickstart`