feat: enhance Vercel service with deployment and domain management

[Folex1275]

Vercel Service Operations Implementation

Overview

This PR implements four related issues for Vercel service operations, adding domain configuration, deployment status retrieval, comprehensive unit tests, and property tests for environment variable configuration.

Changes

Issue #91: Implement Vercel Domain Configuration

Files Modified:

• apps/web/src/services/vercel.service.ts

New Types:

• DomainVerification - DNS verification requirements
• AddDomainRequest - Domain configuration request
• AddDomainResult - Domain addition result with verification
• DomainConfig - Domain configuration details

New Methods:

• addDomain() - Add a domain to a Vercel project or deployment with verification requirements
• removeDomain() - Remove a domain from a Vercel project (best-effort cleanup)
• getDomainConfig() - Get domain configuration and verification status
• verifyDomain() - Verify domain ownership by checking DNS records

New Error Codes:

• DOMAIN_ALREADY_EXISTS - Domain already exists
• DOMAIN_NOT_FOUND - Domain not found
• DOMAIN_VERIFICATION_REQUIRED - Domain verification required

Features:

• Support for project and deployment-level domain assignment
• Returns verification requirements for DNS setup (CNAME, A records)
• Handles known Vercel domain errors cleanly
• Best-effort cleanup for domain removal

---

Issue #92: Implement Retrieval of Vercel Deployment Status

Files Modified:

• apps/web/src/services/vercel.service.ts

New Types:

• VercelDeploymentStatus - Vercel deployment status enum
• VercelDeployment - Vercel deployment details
• NormalizedDeploymentStatus - Internal deployment status

New Methods:

• getDeployment() - Get deployment details from Vercel
• getDeploymentStatus() - Get normalized deployment status
• normalizeDeploymentStatus() - Map Vercel status to internal states
• listDeployments() - List deployments for a project

Status Mappings:

• QUEUED → pending
• BUILDING → building
• READY → ready
• ERROR / FAILED → failed
• CANCELED → canceled

Features:

• Maps provider statuses into internal deployment states
• Preserves relevant timestamps (createdAt, readyAt, failedAt, canceledAt)
• Preserves deployment URLs
• Handles missing deployments and transient provider failures
• Supports pagination with limit parameter

---

Issue #93: Write Unit Tests for Vercel Service Operations

Files Created:

• apps/web/src/services/vercel.service.test.ts

Test Coverage:

validateVercelConfig:

• Valid token present
• Missing token

createProject:

• Success
• Success with environment variables
• Success with team scope
• Auth headers present
• Project exists error
• Auth failure (401)
• Rate limit (429)
• Network error
• Missing token

triggerDeployment:

• Success
• Auth failure
• Rate limit
• Network error

addDomain:

• Success with verification
• Success without verification
• Domain already exists
• Redirect and forceHttps options
• Deployment attachment

removeDomain:

• Success
• Domain not found (best-effort)
• Other errors (logged)

getDomainConfig:

• Success
• Domain not found
• Other errors

verifyDomain:

• Success with requirements
• Success without requirements
• Auth failure

getDeployment:

• Success
• Deployment not found
• Auth failure

getDeploymentStatus:

• Success
• Deployment not found

normalizeDeploymentStatus:

• All status mappings (QUEUED, BUILDING, READY, ERROR, FAILED, CANCELED, unknown)
• Project ID and name inclusion

listDeployments:

• Success
• Empty list
• Auth failure
• Limit parameter

validateAccess:

• Valid token
• Invalid token
• Network throw
• Missing token

deleteProject:

• Success
• Failure (logged but not thrown)

Total Tests: 50+ comprehensive test cases

---

Issue #94: Add Property Test for Vercel Environment Variable Configuration

Files Created:

• apps/web/src/lib/env/env-template-generator.property.test.ts

Property 21: Vercel Environment Variable Configuration

Test Categories:

Required Environment Variables:

• Always includes NEXT_PUBLIC_APP_NAME
• Always includes NEXT_PUBLIC_STELLAR_NETWORK
• Always includes NEXT_PUBLIC_HORIZON_URL
• Always includes NEXT_PUBLIC_NETWORK_PASSPHRASE
• Always includes NEXT_PUBLIC_SUPABASE_URL
• Always includes NEXT_PUBLIC_SUPABASE_ANON_KEY
• Always includes SUPABASE_SERVICE_ROLE_KEY

Environment Variable Values:

• NEXT_PUBLIC_APP_NAME matches branding.appName
• NEXT_PUBLIC_PRIMARY_COLOR matches branding.primaryColor
• NEXT_PUBLIC_STELLAR_NETWORK matches stellar.network
• NEXT_PUBLIC_ENABLE_CHARTS matches features.enableCharts

Environment Variable Targets:

• All variables have valid VercelEnvTarget values
• Public variables target all environments (production, preview, development)
• Secret variables target production and preview only

Environment Variable Types:

• All variables have valid type values
• Public variables are typed as plain
• Secret variables are typed as encrypted

Template-Specific Variables:

• soroban-defi always includes NEXT_PUBLIC_SOROBAN_RPC_URL
• stellar-dex includes NEXT_PUBLIC_ASSET_PAIRS when configured
• soroban-defi includes NEXT_PUBLIC_CONTRACT_ADDRESSES when configured

Structural Invariants:

• All variables have non-empty key and value
• No duplicate keys
• buildEnvVarEntries and buildVercelEnvVars produce consistent keys
• At least 7 environment variables generated

Missing/Invalid Data Handling:

• Handles empty appName
• Handles invalid color format
• Handles undefined optional fields gracefully

Iterations: 100+ per test case

---

Testing

Unit Tests

Run the Vercel service unit tests:

npm test -- apps/web/src/services/vercel.service.test.ts

Property Tests

Run the environment variable property tests:

npm test -- apps/web/src/lib/env/env-template-generator.property.test.ts

---

Edge Cases & Assumptions

Edge Cases Handled:

1. Domain Already Exists - Returns error with DOMAIN_ALREADY_EXISTS code
2. Domain Not Found - Returns null for getDomainConfig, best-effort cleanup for removeDomain
3. Deployment Not Found - Throws UNKNOWN error with descriptive message
4. Rate Limiting - Includes retryAfterMs for client-side backoff
5. Network Errors - Wrapped in NETWORK_ERROR code
6. Auth Failures - Consistent AUTH_FAILED code across all operations
7. Team Scope - Optional VERCEL_TEAM_ID environment variable support

Assumptions:

1. Vercel API token is configured via VERCEL_TOKEN environment variable
2. Team scope is optional and configured via VERCEL_TEAM_ID environment variable
3. Domain verification requires DNS record configuration by the user
4. Deployment status normalization follows the specified mapping
5. Environment variables follow the Vercel API schema

---

Follow-up Work

1. API Routes - Create API routes for domain and deployment status operations
2. UI Components - Build UI for domain configuration and status display
3. Integration Tests - Add integration tests with mocked Vercel API
4. Documentation - Update API documentation with new endpoints
5. Monitoring - Add logging and metrics for Vercel API calls

---

Security Considerations

• All Vercel API calls use Bearer token authentication
• Environment variables are properly typed (plain vs encrypted)
• Secret variables are only deployed to production and preview environments
• Domain verification requires DNS record configuration
• Error messages are sanitized to prevent information leakage

---

Related Issues

Closes #91
Closes #92
Closes #93
Closes #94

---

Checklist

• Code follows project style guidelines
• Self-review completed
• Tests added for new functionality
• Documentation updated
• No breaking changes
• Security considerations addressed
• Edge cases handled
• Error handling implemented
• Property tests run 100+ iterations

[drips-wave]

@Folex1275 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits