@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-reliability-patterns/references/idempotency-keys.md

@@ -0,0 +1,36 @@
+# Idempotency Keys
+
+## 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;
+  }
+}
+```

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

@@ -1,147 +1,319 @@
 ---
 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".
+description: 'Production-ready Vercel REST API patterns with typed fetch wrappers
+  and error handling.
+
+  Use when integrating with the Vercel API programmatically, building deployment tools,
+
+  or establishing team coding standards for Vercel API calls.
+
+  Trigger with phrases like "vercel SDK patterns", "vercel API wrapper",
+
+  "vercel REST API client", "vercel best practices", "idiomatic vercel API".
+
+  '
 allowed-tools: Read, Write, Edit
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- api
+- typescript
+- patterns
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel SDK Patterns
 
 ## Overview
-Production-ready patterns for Vercel SDK usage in TypeScript and Python.
+
+Build a typed, production-ready wrapper around the Vercel REST API (`api.vercel.com`). Covers authentication, pagination, error handling, retry logic, and common endpoint patterns for deployments, projects, and environment variables.
 
 ## Prerequisites
+
 - Completed `vercel-install-auth` setup
-- Familiarity with async/await patterns
-- Understanding of error handling best practices
+- TypeScript project with `strict` mode enabled
+- Vercel access token with appropriate scope
 
 ## Instructions
 
-### Step 1: Implement Singleton Pattern (Recommended)
+### Step 1: Create Typed API Client
+
 ```typescript
-// src/vercel/client.ts
-import { VercelClient } from 'vercel';
+// lib/vercel-client.ts
+interface VercelClientConfig {
+  token: string;
+  teamId?: string;
+  baseUrl?: string;
+}
+
+interface VercelError {
+  error: { code: string; message: string };
+}
+
+class VercelClient {
+  private token: string;
+  private teamId?: string;
+  private baseUrl: string;
 
-let instance: VercelClient | null = null;
+  constructor(config: VercelClientConfig) {
+    this.token = config.token;
+    this.teamId = config.teamId;
+    this.baseUrl = config.baseUrl ?? 'https://api.vercel.com';
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const url = new URL(path, this.baseUrl);
+    if (this.teamId) url.searchParams.set('teamId', this.teamId);
 
-export function getVercelClient(): VercelClient {
-  if (!instance) {
-    instance = new VercelClient({
-      apiKey: process.env.VERCEL_API_KEY!,
-      // Additional options
+    const res = await fetch(url.toString(), {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        'Content-Type': 'application/json',
+      },
+      body: body ? JSON.stringify(body) : undefined,
     });
+
+    if (!res.ok) {
+      const err: VercelError = await res.json();
+      throw new VercelApiError(res.status, err.error.code, err.error.message);
+    }
+
+    // 204 No Content
+    if (res.status === 204) return undefined as T;
+    return res.json() as Promise<T>;
+  }
+
+  // --- Projects ---
+  async listProjects(limit = 20) {
+    return this.request<{ projects: VercelProject[] }>(
+      'GET', `/v9/projects?limit=${limit}`
+    );
+  }
+
+  async getProject(idOrName: string) {
+    return this.request<VercelProject>('GET', `/v9/projects/${idOrName}`);
+  }
+
+  // --- Deployments ---
+  async listDeployments(projectId?: string, limit = 20) {
+    const params = new URLSearchParams({ limit: String(limit) });
+    if (projectId) params.set('projectId', projectId);
+    return this.request<{ deployments: VercelDeployment[] }>(
+      'GET', `/v6/deployments?${params}`
+    );
+  }
+
+  async getDeployment(idOrUrl: string) {
+    return this.request<VercelDeployment>(
+      'GET', `/v13/deployments/${idOrUrl}`
+    );
+  }
+
+  // --- Environment Variables ---
+  async listEnvVars(projectId: string) {
+    return this.request<{ envs: VercelEnvVar[] }>(
+      'GET', `/v9/projects/${projectId}/env`
+    );
+  }
+
+  async createEnvVar(projectId: string, envVar: CreateEnvVarInput) {
+    return this.request<VercelEnvVar>(
+      'POST', `/v9/projects/${projectId}/env`, envVar
+    );
+  }
+
+  // --- Domains ---
+  async listDomains(projectId: string) {
+    return this.request<{ domains: VercelDomain[] }>(
+      'GET', `/v9/projects/${projectId}/domains`
+    );
+  }
+
+  async addDomain(projectId: string, domain: string) {
+    return this.request<VercelDomain>(
+      'POST', `/v9/projects/${projectId}/domains`, { name: domain }
+    );
   }
-  return instance;
 }
 ```
 
-### Step 2: Add Error Handling Wrapper
+### Step 2: Define Types
+
 ```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 };
+// lib/vercel-types.ts
+interface VercelProject {
+  id: string;
+  name: string;
+  framework: string | null;
+  latestDeployments: VercelDeployment[];
+  targets: Record<string, VercelDeployment>;
+  createdAt: number;
+  updatedAt: number;
+}
+
+interface VercelDeployment {
+  uid: string;
+  name: string;
+  url: string;
+  state: 'BUILDING' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY' | 'CANCELED';
+  target: 'production' | 'preview' | null;
+  createdAt: number;
+  buildingAt: number;
+  ready: number;
+  meta: Record<string, string>;
+}
+
+interface VercelEnvVar {
+  id: string;
+  key: string;
+  value: string;
+  type: 'system' | 'encrypted' | 'plain' | 'sensitive';
+  target: ('production' | 'preview' | 'development')[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+interface CreateEnvVarInput {
+  key: string;
+  value: string;
+  type: 'encrypted' | 'plain' | 'sensitive';
+  target: ('production' | 'preview' | 'development')[];
+}
+
+interface VercelDomain {
+  name: string;
+  verified: boolean;
+  redirect: string | null;
+  gitBranch: string | null;
+  createdAt: number;
+  updatedAt: number;
+}
+```
+
+### Step 3: Custom Error Class
+
+```typescript
+// lib/vercel-errors.ts
+class VercelApiError extends Error {
+  constructor(
+    public status: number,
+    public code: string,
+    message: string
+  ) {
+    super(`Vercel API ${status}: [${code}] ${message}`);
+    this.name = 'VercelApiError';
   }
+
+  get isRateLimit(): boolean { return this.status === 429; }
+  get isNotFound(): boolean { return this.status === 404; }
+  get isUnauthorized(): boolean { return this.status === 401 || this.status === 403; }
 }
 ```
 
-### Step 3: Implement Retry Logic
+### Step 4: Retry with Exponential Backoff
+
 ```typescript
+// lib/vercel-retry.ts
 async function withRetry<T>(
-  operation: () => Promise<T>,
+  fn: () => Promise<T>,
   maxRetries = 3,
-  backoffMs = 1000
+  baseDelayMs = 1000
 ): Promise<T> {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
-      return await operation();
+      return await fn();
     } catch (err) {
-      if (attempt === maxRetries) throw err;
-      const delay = backoffMs * Math.pow(2, attempt - 1);
-      await new Promise(r => setTimeout(r, delay));
+      if (err instanceof VercelApiError && err.isRateLimit && attempt < maxRetries) {
+        const delay = baseDelayMs * Math.pow(2, attempt) + Math.random() * 500;
+        console.warn(`Rate limited. Retrying in ${Math.round(delay)}ms...`);
+        await new Promise(r => setTimeout(r, delay));
+        continue;
+      }
+      throw err;
     }
   }
   throw new Error('Unreachable');
 }
+
+// Usage:
+// const projects = await withRetry(() => client.listProjects());
 ```
 
-## Output
-- Type-safe client singleton
-- Robust error handling with structured logging
-- Automatic retry with exponential backoff
-- Runtime validation for API responses
+### Step 5: Paginated Fetching
 
-## 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 |
+```typescript
+// lib/vercel-pagination.ts
+async function* paginateDeployments(
+  client: VercelClient,
+  projectId: string,
+  pageSize = 100
+): AsyncGenerator<VercelDeployment[]> {
+  let until: number | undefined;
 
-## Examples
+  while (true) {
+    const params = new URLSearchParams({ limit: String(pageSize) });
+    if (until) params.set('until', String(until));
+    if (projectId) params.set('projectId', projectId);
 
-### Factory Pattern (Multi-tenant)
-```typescript
-const clients = new Map<string, VercelClient>();
+    const { deployments } = await client.listDeployments(projectId, pageSize);
+    if (deployments.length === 0) break;
 
-export function getClientForTenant(tenantId: string): VercelClient {
-  if (!clients.has(tenantId)) {
-    const apiKey = getTenantApiKey(tenantId);
-    clients.set(tenantId, new VercelClient({ apiKey }));
+    yield deployments;
+    until = deployments[deployments.length - 1].createdAt;
+    if (deployments.length < pageSize) break;
   }
-  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()
-```
+## API Endpoint Quick Reference
 
-### Zod Validation
-```typescript
-import { z } from 'zod';
+| Operation | Method | Endpoint |
+|-----------|--------|----------|
+| List projects | GET | `/v9/projects` |
+| Get project | GET | `/v9/projects/{idOrName}` |
+| Delete project | DELETE | `/v9/projects/{idOrName}` |
+| List deployments | GET | `/v6/deployments` |
+| Create deployment | POST | `/v13/deployments` |
+| Get deployment | GET | `/v13/deployments/{id}` |
+| Delete deployment | DELETE | `/v13/deployments/{id}` |
+| List env vars | GET | `/v9/projects/{id}/env` |
+| Create env var | POST | `/v9/projects/{id}/env` |
+| Edit env var | PATCH | `/v9/projects/{id}/env/{envId}` |
+| Delete env var | DELETE | `/v9/projects/{id}/env/{envId}` |
+| Add domain | POST | `/v9/projects/{id}/domains` |
+| Verify domain | POST | `/v9/projects/{id}/domains/{domain}/verify` |
+| List teams | GET | `/v2/teams` |
 
-const vercelResponseSchema = z.object({
-  id: z.string(),
-  status: z.enum(['active', 'inactive']),
-  createdAt: z.string().datetime(),
-});
-```
+## Output
+
+- Type-safe Vercel API client with full TypeScript coverage
+- Custom error class with semantic helpers (isRateLimit, isNotFound)
+- Automatic retry with exponential backoff for 429 responses
+- Paginated data fetching for large result sets
+
+## Error Handling
+
+| Error | Status | Solution |
+|-------|--------|----------|
+| `forbidden` | 403 | Token lacks scope — regenerate with correct permissions |
+| `not_found` | 404 | Check project/deployment ID is correct |
+| `rate_limited` | 429 | Use `withRetry()` wrapper — waits and retries automatically |
+| `team_not_found` | 404 | Verify `teamId` parameter matches your team |
+| `bad_request` | 400 | Validate request body matches API schema |
 
 ## Resources
-- [Vercel SDK Reference](https://vercel.com/docs/sdk)
-- [Vercel API Types](https://vercel.com/docs/types)
-- [Zod Documentation](https://zod.dev/)
+
+- [Vercel REST API Reference](https://vercel.com/docs/rest-api)
+- [Vercel REST API Endpoints](https://vercel.com/docs/rest-api/reference)
+- [Authentication](https://vercel.com/docs/rest-api#creating-an-access-token)
 
 ## Next Steps
-Apply patterns in `vercel-core-workflow-a` for real-world usage.
+
+Proceed to `vercel-deploy-preview` for preview deployment workflows.

package/skills/vercel-sdk-patterns/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| 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 |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-sdk-patterns/references/examples.md

@@ -0,0 +1,45 @@
+## 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(),
+});
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-sdk-patterns/references/implementation.md

@@ -0,0 +1,67 @@
+## Implementation Guide
+
+### 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');
+}
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*