@intentsolutionsio/vercel-pack 1.0.0

package/skills/vercel-hello-world/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: vercel-hello-world
+description: |
+  Create a minimal working Vercel example.
+  Use when starting a new Vercel integration, testing your setup,
+  or learning basic Vercel API patterns.
+  Trigger with phrases like "vercel hello world", "vercel example",
+  "vercel quick start", "simple vercel code".
+allowed-tools: Read, Write, Edit
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Hello World
+
+## Overview
+Minimal working example demonstrating core Vercel functionality.
+
+## Prerequisites
+- Completed `vercel-install-auth` setup
+- Valid API credentials configured
+- Development environment ready
+
+## Instructions
+
+### Step 1: Create Entry File
+Create a new file for your hello world example.
+
+### Step 2: Import and Initialize Client
+```typescript
+import { VercelClient } from 'vercel';
+
+const client = new VercelClient({
+  apiKey: process.env.VERCEL_API_KEY,
+});
+```
+
+### Step 3: Make Your First API Call
+```typescript
+async function main() {
+  const projects = await vercel.projects.list(); console.log('Projects:', projects.map(p => p.name));
+}
+
+main().catch(console.error);
+```
+
+## Output
+- Working code file with Vercel client initialization
+- Successful API response confirming connection
+- Console output showing:
+```
+Success! Your Vercel connection is working.
+```
+
+## Error Handling
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Import Error | SDK not installed | Verify with `npm list` or `pip show` |
+| Auth Error | Invalid credentials | Check environment variable is set |
+| Timeout | Network issues | Increase timeout or check connectivity |
+| Rate Limit | Too many requests | Wait and retry with exponential backoff |
+
+## Examples
+
+### TypeScript Example
+```typescript
+import { VercelClient } from 'vercel';
+
+const client = new VercelClient({
+  apiKey: process.env.VERCEL_API_KEY,
+});
+
+async function main() {
+  const projects = await vercel.projects.list(); console.log('Projects:', projects.map(p => p.name));
+}
+
+main().catch(console.error);
+```
+
+### Python Example
+```python
+from None import VercelClient
+
+client = VercelClient()
+
+None
+```
+
+## Resources
+- [Vercel Getting Started](https://vercel.com/docs/getting-started)
+- [Vercel API Reference](https://vercel.com/docs/api)
+- [Vercel Examples](https://vercel.com/docs/examples)
+
+## Next Steps
+Proceed to `vercel-local-dev-loop` for development workflow setup.

package/skills/vercel-incident-runbook/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: vercel-incident-runbook
+description: |
+  Execute Vercel incident response procedures with triage, mitigation, and postmortem.
+  Use when responding to Vercel-related outages, investigating errors,
+  or running post-incident reviews for Vercel integration failures.
+  Trigger with phrases like "vercel incident", "vercel outage",
+  "vercel down", "vercel on-call", "vercel emergency", "vercel broken".
+allowed-tools: Read, Grep, Bash(kubectl:*), Bash(curl:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Incident Runbook
+
+## Overview
+Rapid incident response procedures for Vercel-related outages.
+
+## Prerequisites
+- Access to Vercel dashboard and status page
+- kubectl access to production cluster
+- Prometheus/Grafana access
+- Communication channels (Slack, PagerDuty)
+
+## Severity Levels
+
+| Level | Definition | Response Time | Examples |
+|-------|------------|---------------|----------|
+| P1 | Complete outage | < 15 min | Vercel API unreachable |
+| P2 | Degraded service | < 1 hour | High latency, partial failures |
+| P3 | Minor impact | < 4 hours | Webhook delays, non-critical errors |
+| P4 | No user impact | Next business day | Monitoring gaps |
+
+## Quick Triage
+
+```bash
+# 1. Check Vercel status
+curl -s https://www.vercel-status.com | jq
+
+# 2. Check our integration health
+curl -s https://api.yourapp.com/health | jq '.services.vercel'
+
+# 3. Check error rate (last 5 min)
+curl -s localhost:9090/api/v1/query?query=rate(vercel_errors_total[5m])
+
+# 4. Recent error logs
+kubectl logs -l app=vercel-integration --since=5m | grep -i error | tail -20
+```
+
+## Decision Tree
+
+```
+Vercel API returning errors?
+├─ YES: Is status.vercel.com showing incident?
+│   ├─ YES → Wait for Vercel to resolve. Enable fallback.
+│   └─ NO → Our integration issue. Check credentials, config.
+└─ NO: Is our service healthy?
+    ├─ YES → Likely resolved or intermittent. Monitor.
+    └─ NO → Our infrastructure issue. Check pods, memory, network.
+```
+
+## Immediate Actions by Error Type
+
+### 401/403 - Authentication
+```bash
+# Verify API key is set
+kubectl get secret vercel-secrets -o jsonpath='{.data.api-key}' | base64 -d
+
+# Check if key was rotated
+# → Verify in Vercel dashboard
+
+# Remediation: Update secret and restart pods
+kubectl create secret generic vercel-secrets --from-literal=api-key=NEW_KEY --dry-run=client -o yaml | kubectl apply -f -
+kubectl rollout restart deployment/vercel-integration
+```
+
+### 429 - Rate Limited
+```bash
+# Check rate limit headers
+curl -v https://api.vercel.com 2>&1 | grep -i rate
+
+# Enable request queuing
+kubectl set env deployment/vercel-integration RATE_LIMIT_MODE=queue
+
+# Long-term: Contact Vercel for limit increase
+```
+
+### 500/503 - Vercel Errors
+```bash
+# Enable graceful degradation
+kubectl set env deployment/vercel-integration VERCEL_FALLBACK=true
+
+# Notify users of degraded service
+# Update status page
+
+# Monitor Vercel status for resolution
+```
+
+## Communication Templates
+
+### Internal (Slack)
+```
+🔴 P1 INCIDENT: Vercel Integration
+Status: INVESTIGATING
+Impact: [Describe user impact]
+Current action: [What you're doing]
+Next update: [Time]
+Incident commander: @[name]
+```
+
+### External (Status Page)
+```
+Vercel Integration Issue
+
+We're experiencing issues with our Vercel integration.
+Some users may experience [specific impact].
+
+We're actively investigating and will provide updates.
+
+Last updated: [timestamp]
+```
+
+## Post-Incident
+
+### Evidence Collection
+```bash
+# Generate debug bundle
+./scripts/vercel-debug-bundle.sh
+
+# Export relevant logs
+kubectl logs -l app=vercel-integration --since=1h > incident-logs.txt
+
+# Capture metrics
+curl "localhost:9090/api/v1/query_range?query=vercel_errors_total&start=2h" > metrics.json
+```
+
+### Postmortem Template
+```markdown
+## Incident: Vercel [Error Type]
+**Date:** YYYY-MM-DD
+**Duration:** X hours Y minutes
+**Severity:** P[1-4]
+
+### Summary
+[1-2 sentence description]
+
+### Timeline
+- HH:MM - [Event]
+- HH:MM - [Event]
+
+### Root Cause
+[Technical explanation]
+
+### Impact
+- Users affected: N
+- Revenue impact: $X
+
+### Action Items
+- [ ] [Preventive measure] - Owner - Due date
+```
+
+## Instructions
+
+### Step 1: Quick Triage
+Run the triage commands to identify the issue source.
+
+### Step 2: Follow Decision Tree
+Determine if the issue is Vercel-side or internal.
+
+### Step 3: Execute Immediate Actions
+Apply the appropriate remediation for the error type.
+
+### Step 4: Communicate Status
+Update internal and external stakeholders.
+
+## Output
+- Issue identified and categorized
+- Remediation applied
+- Stakeholders notified
+- Evidence collected for postmortem
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Can't reach status page | Network issue | Use mobile or VPN |
+| kubectl fails | Auth expired | Re-authenticate |
+| Metrics unavailable | Prometheus down | Check backup metrics |
+| Secret rotation fails | Permission denied | Escalate to admin |
+
+## Examples
+
+### One-Line Health Check
+```bash
+curl -sf https://api.yourapp.com/health | jq '.services.vercel.status' || echo "UNHEALTHY"
+```
+
+## Resources
+- [Vercel Status Page](https://www.vercel-status.com)
+- [Vercel Support](https://support.vercel.com)
+
+## Next Steps
+For data handling, see `vercel-data-handling`.

package/skills/vercel-install-auth/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: vercel-install-auth
+description: |
+  Install and configure Vercel SDK/CLI authentication.
+  Use when setting up a new Vercel integration, configuring API keys,
+  or initializing Vercel in your project.
+  Trigger with phrases like "install vercel", "setup vercel",
+  "vercel auth", "configure vercel API key".
+allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Install & Auth
+
+## Overview
+Set up Vercel SDK/CLI and configure authentication credentials.
+
+## Prerequisites
+- Node.js 18+ or Python 3.10+
+- Package manager (npm, pnpm, or pip)
+- Vercel account with API access
+- API key from Vercel dashboard
+
+## Instructions
+
+### Step 1: Install SDK
+```bash
+# Node.js
+npm install vercel
+
+# Python
+pip install None
+```
+
+### Step 2: Configure Authentication
+```bash
+# Set environment variable
+export VERCEL_API_KEY="your-api-key"
+
+# Or create .env file
+echo 'VERCEL_API_KEY=your-api-key' >> .env
+```
+
+### Step 3: Verify Connection
+```typescript
+const teams = await vercel.teams.list(); console.log(teams.length > 0 ? 'OK' : 'No teams');
+```
+
+## Output
+- Installed SDK package in node_modules or site-packages
+- Environment variable or .env file with API key
+- Successful connection verification output
+
+## Error Handling
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Invalid API Key | Incorrect or expired key | Verify key in Vercel dashboard |
+| Rate Limited | Exceeded quota | Check quota at https://vercel.com/docs |
+| Network Error | Firewall blocking | Ensure outbound HTTPS allowed |
+| Module Not Found | Installation failed | Run `npm install` or `pip install` again |
+
+## Examples
+
+### TypeScript Setup
+```typescript
+import { VercelClient } from 'vercel';
+
+const client = new VercelClient({
+  apiKey: process.env.VERCEL_API_KEY,
+});
+```
+
+### Python Setup
+```python
+from None import VercelClient
+
+client = VercelClient(
+    api_key=os.environ.get('VERCEL_API_KEY')
+)
+```
+
+## Resources
+- [Vercel Documentation](https://vercel.com/docs)
+- [Vercel Dashboard](https://api.vercel.com)
+- [Vercel Status](https://www.vercel-status.com)
+
+## Next Steps
+After successful auth, proceed to `vercel-hello-world` for your first API call.

package/skills/vercel-known-pitfalls/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: vercel-known-pitfalls
+description: |
+  Identify and avoid Vercel anti-patterns and common integration mistakes.
+  Use when reviewing Vercel code for issues, onboarding new developers,
+  or auditing existing Vercel integrations for best practices violations.
+  Trigger with phrases like "vercel mistakes", "vercel anti-patterns",
+  "vercel pitfalls", "vercel what not to do", "vercel code review".
+allowed-tools: Read, Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Known Pitfalls
+
+## Overview
+Common mistakes and anti-patterns when integrating with Vercel.
+
+## Prerequisites
+- Access to Vercel codebase for review
+- Understanding of async/await patterns
+- Knowledge of security best practices
+- Familiarity with rate limiting concepts
+
+## Pitfall #1: Synchronous API Calls in Request Path
+
+### ❌ Anti-Pattern
+```typescript
+// User waits for Vercel API call
+app.post('/checkout', async (req, res) => {
+  const payment = await vercelClient.processPayment(req.body);  // 2-5s latency
+  const notification = await vercelClient.sendEmail(payment);   // Another 1-2s
+  res.json({ success: true });  // User waited 3-7s
+});
+```
+
+### ✅ Better Approach
+```typescript
+// Return immediately, process async
+app.post('/checkout', async (req, res) => {
+  const jobId = await queue.enqueue('process-checkout', req.body);
+  res.json({ jobId, status: 'processing' });  // 50ms response
+});
+
+// Background job
+async function processCheckout(data) {
+  const payment = await vercelClient.processPayment(data);
+  await vercelClient.sendEmail(payment);
+}
+```
+
+---
+
+## Pitfall #2: Not Handling Rate Limits
+
+### ❌ Anti-Pattern
+```typescript
+// Blast requests, crash on 429
+for (const item of items) {
+  await vercelClient.process(item);  // Will hit rate limit
+}
+```
+
+### ✅ Better Approach
+```typescript
+import pLimit from 'p-limit';
+
+const limit = pLimit(5);  // Max 5 concurrent
+const rateLimiter = new RateLimiter({ tokensPerSecond: 10 });
+
+for (const item of items) {
+  await rateLimiter.acquire();
+  await limit(() => vercelClient.process(item));
+}
+```
+
+---
+
+## Pitfall #3: Leaking API Keys
+
+### ❌ Anti-Pattern
+```typescript
+// In frontend code (visible to users!)
+const client = new VercelClient({
+  apiKey: 'sk_live_ACTUAL_KEY_HERE',  // Anyone can see this
+});
+
+// In git history
+git commit -m "add API key"  // Exposed forever
+```
+
+### ✅ Better Approach
+```typescript
+// Backend only, environment variable
+const client = new VercelClient({
+  apiKey: process.env.VERCEL_API_KEY,
+});
+
+// Use .gitignore
+.env
+.env.local
+.env.*.local
+```
+
+---
+
+## Pitfall #4: Ignoring Idempotency
+
+### ❌ Anti-Pattern
+```typescript
+// Network error on response = duplicate charge!
+try {
+  await vercelClient.charge(order);
+} catch (error) {
+  if (error.code === 'NETWORK_ERROR') {
+    await vercelClient.charge(order);  // Charged twice!
+  }
+}
+```
+
+### ✅ Better Approach
+```typescript
+const idempotencyKey = `order-${order.id}-${Date.now()}`;
+
+await vercelClient.charge(order, {
+  idempotencyKey,  // Safe to retry
+});
+```
+
+---
+
+## Pitfall #5: Not Validating Webhooks
+
+### ❌ Anti-Pattern
+```typescript
+// Trust any incoming request
+app.post('/webhook', (req, res) => {
+  processWebhook(req.body);  // Attacker can send fake events
+  res.sendStatus(200);
+});
+```
+
+### ✅ Better Approach
+```typescript
+app.post('/webhook',
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    const signature = req.headers['x-vercel-signature'];
+    if (!verifyVercelSignature(req.body, signature)) {
+      return res.sendStatus(401);
+    }
+    processWebhook(JSON.parse(req.body));
+    res.sendStatus(200);
+  }
+);
+```
+
+---
+
+## Pitfall #6: Missing Error Handling
+
+### ❌ Anti-Pattern
+```typescript
+// Crashes on any error
+const result = await vercelClient.get(id);
+console.log(result.data.nested.value);  // TypeError if missing
+```
+
+### ✅ Better Approach
+```typescript
+try {
+  const result = await vercelClient.get(id);
+  console.log(result?.data?.nested?.value ?? 'default');
+} catch (error) {
+  if (error instanceof VercelNotFoundError) {
+    return null;
+  }
+  if (error instanceof VercelRateLimitError) {
+    await sleep(error.retryAfter);
+    return this.get(id);  // Retry
+  }
+  throw error;  // Rethrow unknown errors
+}
+```
+
+---
+
+## Pitfall #7: Hardcoding Configuration
+
+### ❌ Anti-Pattern
+```typescript
+const client = new VercelClient({
+  timeout: 5000,  // Too short for some operations
+  baseUrl: 'https://api.vercel.com',  // Can't change for staging
+});
+```
+
+### ✅ Better Approach
+```typescript
+const client = new VercelClient({
+  timeout: parseInt(process.env.VERCEL_TIMEOUT || '30000'),
+  baseUrl: process.env.VERCEL_BASE_URL || 'https://api.vercel.com',
+});
+```
+
+---
+
+## Pitfall #8: Not Implementing Circuit Breaker
+
+### ❌ Anti-Pattern
+```typescript
+// When Vercel is down, every request hangs
+for (const user of users) {
+  await vercelClient.sync(user);  // All timeout sequentially
+}
+```
+
+### ✅ Better Approach
+```typescript
+import CircuitBreaker from 'opossum';
+
+const breaker = new CircuitBreaker(vercelClient.sync, {
+  timeout: 10000,
+  errorThresholdPercentage: 50,
+  resetTimeout: 30000,
+});
+
+// Fails fast when circuit is open
+for (const user of users) {
+  await breaker.fire(user).catch(handleFailure);
+}
+```
+
+---
+
+## Pitfall #9: Logging Sensitive Data
+
+### ❌ Anti-Pattern
+```typescript
+console.log('Request:', JSON.stringify(request));  // Logs API key, PII
+console.log('User:', user);  // Logs email, phone
+```
+
+### ✅ Better Approach
+```typescript
+const redacted = {
+  ...request,
+  apiKey: '[REDACTED]',
+  user: { id: user.id },  // Only non-sensitive fields
+};
+console.log('Request:', JSON.stringify(redacted));
+```
+
+---
+
+## Pitfall #10: No Graceful Degradation
+
+### ❌ Anti-Pattern
+```typescript
+// Entire feature broken if Vercel is down
+const recommendations = await vercelClient.getRecommendations(userId);
+return renderPage({ recommendations });  // Page crashes
+```
+
+### ✅ Better Approach
+```typescript
+let recommendations;
+try {
+  recommendations = await vercelClient.getRecommendations(userId);
+} catch (error) {
+  recommendations = await getFallbackRecommendations(userId);
+  reportDegradedService('vercel', error);
+}
+return renderPage({ recommendations, degraded: !recommendations });
+```
+
+---
+
+## Instructions
+
+### Step 1: Review for Anti-Patterns
+Scan codebase for each pitfall pattern.
+
+### Step 2: Prioritize Fixes
+Address security issues first, then performance.
+
+### Step 3: Implement Better Approach
+Replace anti-patterns with recommended patterns.
+
+### Step 4: Add Prevention
+Set up linting and CI checks to prevent recurrence.
+
+## Output
+- Anti-patterns identified
+- Fixes prioritized and implemented
+- Prevention measures in place
+- Code quality improved
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Too many findings | Legacy codebase | Prioritize security first |
+| Pattern not detected | Complex code | Manual review |
+| False positive | Similar code | Whitelist exceptions |
+| Fix breaks tests | Behavior change | Update tests |
+
+## Examples
+
+### Quick Pitfall Scan
+```bash
+# Check for common pitfalls
+grep -r "sk_live_" --include="*.ts" src/        # Key leakage
+grep -r "console.log" --include="*.ts" src/     # Potential PII logging
+```
+
+## Resources
+- [Vercel Security Guide](https://vercel.com/docs/security)
+- [Vercel Best Practices](https://vercel.com/docs/best-practices)
+
+## Quick Reference Card
+
+| Pitfall | Detection | Prevention |
+|---------|-----------|------------|
+| Sync in request | High latency | Use queues |
+| Rate limit ignore | 429 errors | Implement backoff |
+| Key leakage | Git history scan | Env vars, .gitignore |
+| No idempotency | Duplicate records | Idempotency keys |
+| Unverified webhooks | Security audit | Signature verification |
+| Missing error handling | Crashes | Try-catch, types |
+| Hardcoded config | Code review | Environment variables |
+| No circuit breaker | Cascading failures | opossum, resilience4j |
+| Logging PII | Log audit | Redaction middleware |
+| No degradation | Total outages | Fallback systems |