@intentsolutionsio/vercel-pack 1.0.0

package/skills/vercel-reference-architecture/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: vercel-reference-architecture
+description: |
+  Implement Vercel reference architecture with best-practice project layout.
+  Use when designing new Vercel integrations, reviewing project structure,
+  or establishing architecture standards for Vercel applications.
+  Trigger with phrases like "vercel architecture", "vercel best practices",
+  "vercel project structure", "how to organize vercel", "vercel layout".
+allowed-tools: Read, Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Reference Architecture
+
+## Overview
+Production-ready architecture patterns for Vercel integrations.
+
+## Prerequisites
+- Understanding of layered architecture
+- Vercel SDK knowledge
+- TypeScript project setup
+- Testing framework configured
+
+## Project Structure
+
+```
+my-vercel-project/
+├── src/
+│   ├── vercel/
+│   │   ├── client.ts           # Singleton client wrapper
+│   │   ├── config.ts           # Environment configuration
+│   │   ├── types.ts            # TypeScript types
+│   │   ├── errors.ts           # Custom error classes
+│   │   └── handlers/
+│   │       ├── webhooks.ts     # Webhook handlers
+│   │       └── events.ts       # Event processing
+│   ├── services/
+│   │   └── vercel/
+│   │       ├── index.ts        # Service facade
+│   │       ├── sync.ts         # Data synchronization
+│   │       └── cache.ts        # Caching layer
+│   ├── api/
+│   │   └── vercel/
+│   │       └── webhook.ts      # Webhook endpoint
+│   └── jobs/
+│       └── vercel/
+│           └── sync.ts         # Background sync job
+├── tests/
+│   ├── unit/
+│   │   └── vercel/
+│   └── integration/
+│       └── vercel/
+├── config/
+│   ├── vercel.development.json
+│   ├── vercel.staging.json
+│   └── vercel.production.json
+└── docs/
+    └── vercel/
+        ├── SETUP.md
+        └── RUNBOOK.md
+```
+
+## Layer Architecture
+
+```
+┌─────────────────────────────────────────┐
+│             API Layer                    │
+│   (Controllers, Routes, Webhooks)        │
+├─────────────────────────────────────────┤
+│           Service Layer                  │
+│  (Business Logic, Orchestration)         │
+├─────────────────────────────────────────┤
+│          Vercel Layer        │
+│   (Client, Types, Error Handling)        │
+├─────────────────────────────────────────┤
+│         Infrastructure Layer             │
+│    (Cache, Queue, Monitoring)            │
+└─────────────────────────────────────────┘
+```
+
+## Key Components
+
+### Step 1: Client Wrapper
+```typescript
+// src/vercel/client.ts
+export class VercelService {
+  private client: VercelClient;
+  private cache: Cache;
+  private monitor: Monitor;
+
+  constructor(config: VercelConfig) {
+    this.client = new VercelClient(config);
+    this.cache = new Cache(config.cacheOptions);
+    this.monitor = new Monitor('vercel');
+  }
+
+  async get(id: string): Promise<Resource> {
+    return this.cache.getOrFetch(id, () =>
+      this.monitor.track('get', () => this.client.get(id))
+    );
+  }
+}
+```
+
+### Step 2: Error Boundary
+```typescript
+// src/vercel/errors.ts
+export class VercelServiceError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly retryable: boolean,
+    public readonly originalError?: Error
+  ) {
+    super(message);
+    this.name = 'VercelServiceError';
+  }
+}
+
+export function wrapVercelError(error: unknown): VercelServiceError {
+  // Transform SDK errors to application errors
+}
+```
+
+### Step 3: Health Check
+```typescript
+// src/vercel/health.ts
+export async function checkVercelHealth(): Promise<HealthStatus> {
+  try {
+    const start = Date.now();
+    await vercelClient.ping();
+    return {
+      status: 'healthy',
+      latencyMs: Date.now() - start,
+    };
+  } catch (error) {
+    return { status: 'unhealthy', error: error.message };
+  }
+}
+```
+
+## Data Flow Diagram
+
+```
+User Request
+     │
+     ▼
+┌─────────────┐
+│   API       │
+│   Gateway   │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐    ┌─────────────┐
+│   Service   │───▶│   Cache     │
+│   Layer     │    │   (Redis)   │
+└──────┬──────┘    └─────────────┘
+       │
+       ▼
+┌─────────────┐
+│ Vercel    │
+│   Client    │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│ Vercel    │
+│   API       │
+└─────────────┘
+```
+
+## Configuration Management
+
+```typescript
+// config/vercel.ts
+export interface VercelConfig {
+  apiKey: string;
+  environment: 'development' | 'staging' | 'production';
+  timeout: number;
+  retries: number;
+  cache: {
+    enabled: boolean;
+    ttlSeconds: number;
+  };
+}
+
+export function loadVercelConfig(): VercelConfig {
+  const env = process.env.NODE_ENV || 'development';
+  return require(`./vercel.${env}.json`);
+}
+```
+
+## Instructions
+
+### Step 1: Create Directory Structure
+Set up the project layout following the reference structure above.
+
+### Step 2: Implement Client Wrapper
+Create the singleton client with caching and monitoring.
+
+### Step 3: Add Error Handling
+Implement custom error classes for Vercel operations.
+
+### Step 4: Configure Health Checks
+Add health check endpoint for Vercel connectivity.
+
+## Output
+- Structured project layout
+- Client wrapper with caching
+- Error boundary implemented
+- Health checks configured
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Circular dependencies | Wrong layering | Separate concerns by layer |
+| Config not loading | Wrong paths | Verify config file locations |
+| Type errors | Missing types | Add Vercel types |
+| Test isolation | Shared state | Use dependency injection |
+
+## Examples
+
+### Quick Setup Script
+```bash
+# Create reference structure
+mkdir -p src/vercel/{handlers} src/services/vercel src/api/vercel
+touch src/vercel/{client,config,types,errors}.ts
+touch src/services/vercel/{index,sync,cache}.ts
+```
+
+## Resources
+- [Vercel SDK Documentation](https://vercel.com/docs/sdk)
+- [Vercel Best Practices](https://vercel.com/docs/best-practices)
+
+## Flagship Skills
+For multi-environment setup, see `vercel-multi-env-setup`.

package/skills/vercel-reliability-patterns/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: vercel-reliability-patterns
+description: |
+  Implement Vercel reliability patterns including circuit breakers, idempotency, and graceful degradation.
+  Use when building fault-tolerant Vercel integrations, implementing retry strategies,
+  or adding resilience to production Vercel services.
+  Trigger with phrases like "vercel reliability", "vercel circuit breaker",
+  "vercel idempotent", "vercel resilience", "vercel fallback", "vercel bulkhead".
+allowed-tools: Read, Write, Edit
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Reliability Patterns
+
+## Overview
+Production-grade reliability patterns for Vercel integrations.
+
+## Prerequisites
+- Understanding of circuit breaker pattern
+- opossum or similar library installed
+- Queue infrastructure for DLQ
+- Caching layer for fallbacks
+
+## Circuit Breaker
+
+```typescript
+import CircuitBreaker from 'opossum';
+
+const vercelBreaker = new CircuitBreaker(
+  async (operation: () => Promise<any>) => operation(),
+  {
+    timeout: 10000,
+    errorThresholdPercentage: 50,
+    resetTimeout: 30000,
+    volumeThreshold: 10,
+  }
+);
+
+// Events
+vercelBreaker.on('open', () => {
+  console.warn('Vercel circuit OPEN - requests failing fast');
+  alertOps('Vercel circuit breaker opened');
+});
+
+vercelBreaker.on('halfOpen', () => {
+  console.info('Vercel circuit HALF-OPEN - testing recovery');
+});
+
+vercelBreaker.on('close', () => {
+  console.info('Vercel circuit CLOSED - normal operation');
+});
+
+// Usage
+async function safeVercelCall<T>(fn: () => Promise<T>): Promise<T> {
+  return vercelBreaker.fire(fn);
+}
+```
+
+## Idempotency Keys
+
+```typescript
+import { v4 as uuidv4 } from 'uuid';
+import crypto from 'crypto';
+
+// Generate deterministic idempotency key from input
+function generateIdempotencyKey(
+  operation: string,
+  params: Record<string, any>
+): string {
+  const data = JSON.stringify({ operation, params });
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+// Or use random key with storage
+class IdempotencyManager {
+  private store: Map<string, { key: string; expiresAt: Date }> = new Map();
+
+  getOrCreate(operationId: string): string {
+    const existing = this.store.get(operationId);
+    if (existing && existing.expiresAt > new Date()) {
+      return existing.key;
+    }
+
+    const key = uuidv4();
+    this.store.set(operationId, {
+      key,
+      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
+    });
+    return key;
+  }
+}
+```
+
+## Bulkhead Pattern
+
+```typescript
+import PQueue from 'p-queue';
+
+// Separate queues for different operations
+const vercelQueues = {
+  critical: new PQueue({ concurrency: 10 }),
+  normal: new PQueue({ concurrency: 5 }),
+  bulk: new PQueue({ concurrency: 2 }),
+};
+
+async function prioritizedVercelCall<T>(
+  priority: 'critical' | 'normal' | 'bulk',
+  fn: () => Promise<T>
+): Promise<T> {
+  return vercelQueues[priority].add(fn);
+}
+
+// Usage
+await prioritizedVercelCall('critical', () =>
+  vercelClient.processPayment(order)
+);
+
+await prioritizedVercelCall('bulk', () =>
+  vercelClient.syncCatalog(products)
+);
+```
+
+## Timeout Hierarchy
+
+```typescript
+const TIMEOUT_CONFIG = {
+  connect: 5000,      // Initial connection
+  request: 30000,     // Standard requests
+  upload: 120000,     // File uploads
+  longPoll: 300000,   // Webhook long-polling
+};
+
+async function timedoutVercelCall<T>(
+  operation: 'connect' | 'request' | 'upload' | 'longPoll',
+  fn: () => Promise<T>
+): Promise<T> {
+  const timeout = TIMEOUT_CONFIG[operation];
+
+  return Promise.race([
+    fn(),
+    new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error(`Vercel ${operation} timeout`)), timeout)
+    ),
+  ]);
+}
+```
+
+## Graceful Degradation
+
+```typescript
+interface VercelFallback {
+  enabled: boolean;
+  data: any;
+  staleness: 'fresh' | 'stale' | 'very_stale';
+}
+
+async function withVercelFallback<T>(
+  fn: () => Promise<T>,
+  fallbackFn: () => Promise<T>
+): Promise<{ data: T; fallback: boolean }> {
+  try {
+    const data = await fn();
+    // Update cache for future fallback
+    await updateFallbackCache(data);
+    return { data, fallback: false };
+  } catch (error) {
+    console.warn('Vercel failed, using fallback:', error.message);
+    const data = await fallbackFn();
+    return { data, fallback: true };
+  }
+}
+```
+
+## Dead Letter Queue
+
+```typescript
+interface DeadLetterEntry {
+  id: string;
+  operation: string;
+  payload: any;
+  error: string;
+  attempts: number;
+  lastAttempt: Date;
+}
+
+class VercelDeadLetterQueue {
+  private queue: DeadLetterEntry[] = [];
+
+  add(entry: Omit<DeadLetterEntry, 'id' | 'lastAttempt'>): void {
+    this.queue.push({
+      ...entry,
+      id: uuidv4(),
+      lastAttempt: new Date(),
+    });
+  }
+
+  async processOne(): Promise<boolean> {
+    const entry = this.queue.shift();
+    if (!entry) return false;
+
+    try {
+      await vercelClient[entry.operation](entry.payload);
+      console.log(`DLQ: Successfully reprocessed ${entry.id}`);
+      return true;
+    } catch (error) {
+      entry.attempts++;
+      entry.lastAttempt = new Date();
+
+      if (entry.attempts < 5) {
+        this.queue.push(entry);
+      } else {
+        console.error(`DLQ: Giving up on ${entry.id} after 5 attempts`);
+        await alertOnPermanentFailure(entry);
+      }
+      return false;
+    }
+  }
+}
+```
+
+## Health Check with Degraded State
+
+```typescript
+type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';
+
+async function vercelHealthCheck(): Promise<{
+  status: HealthStatus;
+  details: Record<string, any>;
+}> {
+  const checks = {
+    api: await checkApiConnectivity(),
+    circuitBreaker: vercelBreaker.stats(),
+    dlqSize: deadLetterQueue.size(),
+  };
+
+  const status: HealthStatus =
+    !checks.api.connected ? 'unhealthy' :
+    checks.circuitBreaker.state === 'open' ? 'degraded' :
+    checks.dlqSize > 100 ? 'degraded' :
+    'healthy';
+
+  return { status, details: checks };
+}
+```
+
+## Instructions
+
+### Step 1: Implement Circuit Breaker
+Wrap Vercel calls with circuit breaker.
+
+### Step 2: Add Idempotency Keys
+Generate deterministic keys for operations.
+
+### Step 3: Configure Bulkheads
+Separate queues for different priorities.
+
+### Step 4: Set Up Dead Letter Queue
+Handle permanent failures gracefully.
+
+## Output
+- Circuit breaker protecting Vercel calls
+- Idempotency preventing duplicates
+- Bulkhead isolation implemented
+- DLQ for failed operations
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Circuit stays open | Threshold too low | Adjust error percentage |
+| Duplicate operations | Missing idempotency | Add idempotency key |
+| Queue full | Rate too high | Increase concurrency |
+| DLQ growing | Persistent failures | Investigate root cause |
+
+## Examples
+
+### Quick Circuit Check
+```typescript
+const state = vercelBreaker.stats().state;
+console.log('Vercel circuit:', state);
+```
+
+## Resources
+- [Circuit Breaker Pattern](https://martinfowler.com/bliki/CircuitBreaker.html)
+- [Opossum Documentation](https://nodeshift.dev/opossum/)
+- [Vercel Reliability Guide](https://vercel.com/docs/reliability)
+
+## Next Steps
+For policy enforcement, see `vercel-policy-guardrails`.

package/skills/vercel-sdk-patterns/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: vercel-sdk-patterns
+description: |
+  Apply production-ready Vercel SDK patterns for TypeScript and Python.
+  Use when implementing Vercel integrations, refactoring SDK usage,
+  or establishing team coding standards for Vercel.
+  Trigger with phrases like "vercel SDK patterns", "vercel best practices",
+  "vercel code patterns", "idiomatic vercel".
+allowed-tools: Read, Write, Edit
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel SDK Patterns
+
+## Overview
+Production-ready patterns for Vercel SDK usage in TypeScript and Python.
+
+## Prerequisites
+- Completed `vercel-install-auth` setup
+- Familiarity with async/await patterns
+- Understanding of error handling best practices
+
+## Instructions
+
+### Step 1: Implement Singleton Pattern (Recommended)
+```typescript
+// src/vercel/client.ts
+import { VercelClient } from 'vercel';
+
+let instance: VercelClient | null = null;
+
+export function getVercelClient(): VercelClient {
+  if (!instance) {
+    instance = new VercelClient({
+      apiKey: process.env.VERCEL_API_KEY!,
+      // Additional options
+    });
+  }
+  return instance;
+}
+```
+
+### Step 2: Add Error Handling Wrapper
+```typescript
+import { VercelError } from 'vercel';
+
+async function safeVercelCall<T>(
+  operation: () => Promise<T>
+): Promise<{ data: T | null; error: Error | null }> {
+  try {
+    const data = await operation();
+    return { data, error: null };
+  } catch (err) {
+    if (err instanceof VercelError) {
+      console.error({
+        code: err.code,
+        message: err.message,
+      });
+    }
+    return { data: null, error: err as Error };
+  }
+}
+```
+
+### Step 3: Implement Retry Logic
+```typescript
+async function withRetry<T>(
+  operation: () => Promise<T>,
+  maxRetries = 3,
+  backoffMs = 1000
+): Promise<T> {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (err) {
+      if (attempt === maxRetries) throw err;
+      const delay = backoffMs * Math.pow(2, attempt - 1);
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+  throw new Error('Unreachable');
+}
+```
+
+## Output
+- Type-safe client singleton
+- Robust error handling with structured logging
+- Automatic retry with exponential backoff
+- Runtime validation for API responses
+
+## Error Handling
+| Pattern | Use Case | Benefit |
+|---------|----------|---------|
+| Safe wrapper | All API calls | Prevents uncaught exceptions |
+| Retry logic | Transient failures | Improves reliability |
+| Type guards | Response validation | Catches API changes |
+| Logging | All operations | Debugging and monitoring |
+
+## Examples
+
+### Factory Pattern (Multi-tenant)
+```typescript
+const clients = new Map<string, VercelClient>();
+
+export function getClientForTenant(tenantId: string): VercelClient {
+  if (!clients.has(tenantId)) {
+    const apiKey = getTenantApiKey(tenantId);
+    clients.set(tenantId, new VercelClient({ apiKey }));
+  }
+  return clients.get(tenantId)!;
+}
+```
+
+### Python Context Manager
+```python
+from contextlib import asynccontextmanager
+from None import VercelClient
+
+@asynccontextmanager
+async def get_vercel_client():
+    client = VercelClient()
+    try:
+        yield client
+    finally:
+        await client.close()
+```
+
+### Zod Validation
+```typescript
+import { z } from 'zod';
+
+const vercelResponseSchema = z.object({
+  id: z.string(),
+  status: z.enum(['active', 'inactive']),
+  createdAt: z.string().datetime(),
+});
+```
+
+## Resources
+- [Vercel SDK Reference](https://vercel.com/docs/sdk)
+- [Vercel API Types](https://vercel.com/docs/types)
+- [Zod Documentation](https://zod.dev/)
+
+## Next Steps
+Apply patterns in `vercel-core-workflow-a` for real-world usage.