@intentsolutionsio/vercel-pack 1.0.0

package/skills/vercel-ci-integration/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: vercel-ci-integration
+description: |
+  Configure Vercel CI/CD integration with GitHub Actions and testing.
+  Use when setting up automated testing, configuring CI pipelines,
+  or integrating Vercel tests into your build process.
+  Trigger with phrases like "vercel CI", "vercel GitHub Actions",
+  "vercel automated tests", "CI vercel".
+allowed-tools: Read, Write, Edit, Bash(gh:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel CI Integration
+
+## Overview
+Set up CI/CD pipelines for Vercel integrations with automated testing.
+
+## Prerequisites
+- GitHub repository with Actions enabled
+- Vercel test API key
+- npm/pnpm project configured
+
+## Instructions
+
+### Step 1: Create GitHub Actions Workflow
+Create `.github/workflows/vercel-integration.yml`:
+
+```yaml
+name: Vercel Integration Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  VERCEL_API_KEY: ${{ secrets.VERCEL_API_KEY }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      VERCEL_API_KEY: ${{ secrets.VERCEL_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test -- --coverage
+      - run: npm run test:integration
+```
+
+### Step 2: Configure Secrets
+```bash
+gh secret set VERCEL_API_KEY --body "sk_test_***"
+```
+
+### Step 3: Add Integration Tests
+```typescript
+describe('Vercel Integration', () => {
+  it.skipIf(!process.env.VERCEL_API_KEY)('should connect', async () => {
+    const client = getVercelClient();
+    const result = await client.healthCheck();
+    expect(result.status).toBe('ok');
+  });
+});
+```
+
+## Output
+- Automated test pipeline
+- PR checks configured
+- Coverage reports uploaded
+- Release workflow ready
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Secret not found | Missing configuration | Add secret via `gh secret set` |
+| Tests timeout | Network issues | Increase timeout or mock |
+| Auth failures | Invalid key | Check secret value |
+
+## Examples
+
+### Release Workflow
+```yaml
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      VERCEL_API_KEY: ${{ secrets.VERCEL_API_KEY_PROD }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - name: Verify Vercel production readiness
+        run: npm run test:integration
+      - run: npm run build
+      - run: npm publish
+```
+
+### Branch Protection
+```yaml
+required_status_checks:
+  - "test"
+  - "vercel-integration"
+```
+
+## Resources
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Vercel CI Guide](https://vercel.com/docs/ci)
+
+## Next Steps
+For deployment patterns, see `vercel-deploy-integration`.

package/skills/vercel-common-errors/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: vercel-common-errors
+description: |
+  Diagnose and fix Vercel common errors and exceptions.
+  Use when encountering Vercel errors, debugging failed requests,
+  or troubleshooting integration issues.
+  Trigger with phrases like "vercel error", "fix vercel",
+  "vercel not working", "debug vercel".
+allowed-tools: Read, Grep, Bash(curl:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Common Errors
+
+## Overview
+Quick reference for the top 10 most common Vercel errors and their solutions.
+
+## Prerequisites
+- Vercel SDK installed
+- API credentials configured
+- Access to error logs
+
+## Instructions
+
+### Step 1: Identify the Error
+Check error message and code in your logs or console.
+
+### Step 2: Find Matching Error Below
+Match your error to one of the documented cases.
+
+### Step 3: Apply Solution
+Follow the solution steps for your specific error.
+
+## Output
+- Identified error cause
+- Applied fix
+- Verified resolution
+
+## Error Handling
+
+### Build Failed
+**Error Message:**
+```
+Command 'npm run build' exited with 1
+```
+
+**Cause:** Build script failed due to errors in code or dependencies
+
+**Solution:**
+```bash
+Check build logs in Vercel dashboard. Run 'npm run build' locally to reproduce.
+```
+
+---
+
+### Function Timeout
+**Error Message:**
+```
+FUNCTION_INVOCATION_TIMEOUT
+```
+
+**Cause:** Serverless function exceeded execution time limit
+
+**Solution:**
+Optimize function code, use Edge Runtime, or upgrade plan for longer timeouts.
+
+---
+
+### Domain Verification Failed
+**Error Message:**
+```
+Domain verification failed
+```
+
+**Cause:** DNS records not configured correctly
+
+**Solution:**
+```typescript
+Add required CNAME or A records. Wait for DNS propagation (up to 48h).
+```
+
+## Examples
+
+### Quick Diagnostic Commands
+```bash
+# Check Vercel status
+curl -s https://www.vercel-status.com
+
+# Verify API connectivity
+curl -I https://api.vercel.com
+
+# Check local configuration
+env | grep VERCEL
+```
+
+### Escalation Path
+1. Collect evidence with `vercel-debug-bundle`
+2. Check Vercel status page
+3. Contact support with request ID
+
+## Resources
+- [Vercel Status Page](https://www.vercel-status.com)
+- [Vercel Support](https://vercel.com/docs/support)
+- [Vercel Error Codes](https://vercel.com/docs/errors)
+
+## Next Steps
+For comprehensive debugging, see `vercel-debug-bundle`.

package/skills/vercel-cost-tuning/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: vercel-cost-tuning
+description: |
+  Optimize Vercel costs through tier selection, sampling, and usage monitoring.
+  Use when analyzing Vercel billing, reducing API costs,
+  or implementing usage monitoring and budget alerts.
+  Trigger with phrases like "vercel cost", "vercel billing",
+  "reduce vercel costs", "vercel pricing", "vercel expensive", "vercel budget".
+allowed-tools: Read, Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Cost Tuning
+
+## Overview
+Optimize Vercel costs through smart tier selection, sampling, and usage monitoring.
+
+## Prerequisites
+- Access to Vercel billing dashboard
+- Understanding of current usage patterns
+- Database for usage tracking (optional)
+- Alerting system configured (optional)
+
+## Pricing Tiers
+
+| Tier | Monthly Cost | Included | Overage |
+|------|-------------|----------|---------|
+| Hobby | $0 | 100GB bandwidth, 100GB-hrs functions | N/A |
+| Pro | $20 | 1TB bandwidth, 1000GB-hrs functions | $0.001/request |
+| Enterprise | Custom | Unlimited | Volume discounts |
+
+## Cost Estimation
+
+```typescript
+interface UsageEstimate {
+  requestsPerMonth: number;
+  tier: string;
+  estimatedCost: number;
+  recommendation?: string;
+}
+
+function estimateVercelCost(requestsPerMonth: number): UsageEstimate {
+  if (requestsPerMonth <= 1000) {
+    return { requestsPerMonth, tier: 'Free', estimatedCost: 0 };
+  }
+
+  if (requestsPerMonth <= 100000) {
+    return { requestsPerMonth, tier: 'Pro', estimatedCost: 20 };
+  }
+
+  const proOverage = (requestsPerMonth - 100000) * 0.001;
+  const proCost = 20 + proOverage;
+
+  return {
+    requestsPerMonth,
+    tier: 'Pro (with overage)',
+    estimatedCost: proCost,
+    recommendation: proCost > 500
+      ? 'Consider Enterprise tier for volume discounts'
+      : undefined,
+  };
+}
+```
+
+## Usage Monitoring
+
+```typescript
+class VercelUsageMonitor {
+  private requestCount = 0;
+  private bytesTransferred = 0;
+  private alertThreshold: number;
+
+  constructor(monthlyBudget: number) {
+    this.alertThreshold = monthlyBudget * 0.8; // 80% warning
+  }
+
+  track(request: { bytes: number }) {
+    this.requestCount++;
+    this.bytesTransferred += request.bytes;
+
+    if (this.estimatedCost() > this.alertThreshold) {
+      this.sendAlert('Approaching Vercel budget limit');
+    }
+  }
+
+  estimatedCost(): number {
+    return estimateVercelCost(this.requestCount).estimatedCost;
+  }
+
+  private sendAlert(message: string) {
+    // Send to Slack, email, PagerDuty, etc.
+  }
+}
+```
+
+## Cost Reduction Strategies
+
+### Step 1: Request Sampling
+```typescript
+function shouldSample(samplingRate = 0.1): boolean {
+  return Math.random() < samplingRate;
+}
+
+// Use for non-critical telemetry
+if (shouldSample(0.1)) { // 10% sample
+  await vercelClient.trackEvent(event);
+}
+```
+
+### Step 2: Batching Requests
+```typescript
+// Instead of N individual calls
+await Promise.all(ids.map(id => vercelClient.get(id)));
+
+// Use batch endpoint (1 call)
+await vercelClient.batchGet(ids);
+```
+
+### Step 3: Caching (from P16)
+- Cache frequently accessed data
+- Use cache invalidation webhooks
+- Set appropriate TTLs
+
+### Step 4: Compression
+```typescript
+const client = new VercelClient({
+  compression: true, // Enable gzip
+});
+```
+
+## Budget Alerts
+
+```bash
+# Set up billing alerts in Vercel dashboard
+# Or use API if available:
+# Check Vercel documentation for billing APIs
+```
+
+## Cost Dashboard Query
+
+```sql
+-- If tracking usage in your database
+SELECT
+  DATE_TRUNC('day', created_at) as date,
+  COUNT(*) as requests,
+  SUM(response_bytes) as bytes,
+  COUNT(*) * 0.001 as estimated_cost
+FROM vercel_api_logs
+WHERE created_at >= NOW() - INTERVAL '30 days'
+GROUP BY 1
+ORDER BY 1;
+```
+
+## Instructions
+
+### Step 1: Analyze Current Usage
+Review Vercel dashboard for usage patterns and costs.
+
+### Step 2: Select Optimal Tier
+Use the cost estimation function to find the right tier.
+
+### Step 3: Implement Monitoring
+Add usage tracking to catch budget overruns early.
+
+### Step 4: Apply Optimizations
+Enable batching, caching, and sampling where appropriate.
+
+## Output
+- Optimized tier selection
+- Usage monitoring implemented
+- Budget alerts configured
+- Cost reduction strategies applied
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Unexpected charges | Untracked usage | Implement monitoring |
+| Overage fees | Wrong tier | Upgrade tier |
+| Budget exceeded | No alerts | Set up alerts |
+| Inefficient usage | No batching | Enable batch requests |
+
+## Examples
+
+### Quick Cost Check
+```typescript
+// Estimate monthly cost for your usage
+const estimate = estimateVercelCost(yourMonthlyRequests);
+console.log(`Tier: ${estimate.tier}, Cost: $${estimate.estimatedCost}`);
+if (estimate.recommendation) {
+  console.log(`💡 ${estimate.recommendation}`);
+}
+```
+
+## Resources
+- [Vercel Pricing](https://vercel.com/pricing)
+- [Vercel Billing Dashboard](https://dashboard.vercel.com/billing)
+
+## Next Steps
+For architecture patterns, see `vercel-reference-architecture`.

package/skills/vercel-data-handling/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: vercel-data-handling
+description: |
+  Implement Vercel PII handling, data retention, and GDPR/CCPA compliance patterns.
+  Use when handling sensitive data, implementing data redaction, configuring retention policies,
+  or ensuring compliance with privacy regulations for Vercel integrations.
+  Trigger with phrases like "vercel data", "vercel PII",
+  "vercel GDPR", "vercel data retention", "vercel privacy", "vercel CCPA".
+allowed-tools: Read, Write, Edit
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Data Handling
+
+## Overview
+Handle sensitive data correctly when integrating with Vercel.
+
+## Prerequisites
+- Understanding of GDPR/CCPA requirements
+- Vercel SDK with data export capabilities
+- Database for audit logging
+- Scheduled job infrastructure for cleanup
+
+## Data Classification
+
+| Category | Examples | Handling |
+|----------|----------|----------|
+| PII | Email, name, phone | Encrypt, minimize |
+| Sensitive | API keys, tokens | Never log, rotate |
+| Business | Usage metrics | Aggregate when possible |
+| Public | Product names | Standard handling |
+
+## PII Detection
+
+```typescript
+const PII_PATTERNS = [
+  { type: 'email', regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g },
+  { type: 'phone', regex: /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g },
+  { type: 'ssn', regex: /\b\d{3}-\d{2}-\d{4}\b/g },
+  { type: 'credit_card', regex: /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g },
+];
+
+function detectPII(text: string): { type: string; match: string }[] {
+  const findings: { type: string; match: string }[] = [];
+
+  for (const pattern of PII_PATTERNS) {
+    const matches = text.matchAll(pattern.regex);
+    for (const match of matches) {
+      findings.push({ type: pattern.type, match: match[0] });
+    }
+  }
+
+  return findings;
+}
+```
+
+## Data Redaction
+
+```typescript
+function redactPII(data: Record<string, any>): Record<string, any> {
+  const sensitiveFields = ['email', 'phone', 'ssn', 'password', 'apiKey'];
+  const redacted = { ...data };
+
+  for (const field of sensitiveFields) {
+    if (redacted[field]) {
+      redacted[field] = '[REDACTED]';
+    }
+  }
+
+  return redacted;
+}
+
+// Use in logging
+console.log('Vercel request:', redactPII(requestData));
+```
+
+## Data Retention Policy
+
+### Retention Periods
+| Data Type | Retention | Reason |
+|-----------|-----------|--------|
+| API logs | 30 days | Debugging |
+| Error logs | 90 days | Root cause analysis |
+| Audit logs | 7 years | Compliance |
+| PII | Until deletion request | GDPR/CCPA |
+
+### Automatic Cleanup
+
+```typescript
+async function cleanupVercelData(retentionDays: number): Promise<void> {
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - retentionDays);
+
+  await db.vercelLogs.deleteMany({
+    createdAt: { $lt: cutoff },
+    type: { $nin: ['audit', 'compliance'] },
+  });
+}
+
+// Schedule daily cleanup
+cron.schedule('0 3 * * *', () => cleanupVercelData(30));
+```
+
+## GDPR/CCPA Compliance
+
+### Data Subject Access Request (DSAR)
+
+```typescript
+async function exportUserData(userId: string): Promise<DataExport> {
+  const vercelData = await vercelClient.getUserData(userId);
+
+  return {
+    source: 'Vercel',
+    exportedAt: new Date().toISOString(),
+    data: {
+      profile: vercelData.profile,
+      activities: vercelData.activities,
+      // Include all user-related data
+    },
+  };
+}
+```
+
+### Right to Deletion
+
+```typescript
+async function deleteUserData(userId: string): Promise<DeletionResult> {
+  // 1. Delete from Vercel
+  await vercelClient.deleteUser(userId);
+
+  // 2. Delete local copies
+  await db.vercelUserCache.deleteMany({ userId });
+
+  // 3. Audit log (required to keep)
+  await auditLog.record({
+    action: 'GDPR_DELETION',
+    userId,
+    service: 'vercel',
+    timestamp: new Date(),
+  });
+
+  return { success: true, deletedAt: new Date() };
+}
+```
+
+## Data Minimization
+
+```typescript
+// Only request needed fields
+const user = await vercelClient.getUser(userId, {
+  fields: ['id', 'name'], // Not email, phone, address
+});
+
+// Don't store unnecessary data
+const cacheData = {
+  id: user.id,
+  name: user.name,
+  // Omit sensitive fields
+};
+```
+
+## Instructions
+
+### Step 1: Classify Data
+Categorize all Vercel data by sensitivity level.
+
+### Step 2: Implement PII Detection
+Add regex patterns to detect sensitive data in logs.
+
+### Step 3: Configure Redaction
+Apply redaction to sensitive fields before logging.
+
+### Step 4: Set Up Retention
+Configure automatic cleanup with appropriate retention periods.
+
+## Output
+- Data classification documented
+- PII detection implemented
+- Redaction in logging active
+- Retention policy enforced
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| PII in logs | Missing redaction | Wrap logging with redact |
+| Deletion failed | Data locked | Check dependencies |
+| Export incomplete | Timeout | Increase batch size |
+| Audit gap | Missing entries | Review log pipeline |
+
+## Examples
+
+### Quick PII Scan
+```typescript
+const findings = detectPII(JSON.stringify(userData));
+if (findings.length > 0) {
+  console.warn(`PII detected: ${findings.map(f => f.type).join(', ')}`);
+}
+```
+
+### Redact Before Logging
+```typescript
+const safeData = redactPII(apiResponse);
+logger.info('Vercel response:', safeData);
+```
+
+### GDPR Data Export
+```typescript
+const userExport = await exportUserData('user-123');
+await sendToUser(userExport);
+```
+
+## Resources
+- [GDPR Developer Guide](https://gdpr.eu/developers/)
+- [CCPA Compliance Guide](https://oag.ca.gov/privacy/ccpa)
+- [Vercel Privacy Guide](https://vercel.com/docs/privacy)
+
+## Next Steps
+For enterprise access control, see `vercel-enterprise-rbac`.