@vasperacapital/vaspera-shared 0.1.0

package/src/__tests__/errors.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createError,
+  createErrorResponse,
+  Errors,
+  VasperaApiError,
+} from '../errors/factory.js';
+import { ErrorCodes } from '../errors/codes.js';
+
+describe('Error Handling', () => {
+  describe('createError', () => {
+    it('should create error with required fields', () => {
+      const error = createError(ErrorCodes.AUTH.REQUIRED);
+
+      expect(error.code).toBe('VPM-AUTH-001');
+      expect(error.message).toBe('Authentication required');
+      expect(error.timestamp).toBeDefined();
+      expect(error.requestId).toMatch(/^req_/);
+      expect(error.docUrl).toBe('https://docs.vaspera.pm/errors/VPM-AUTH-001');
+    });
+
+    it('should include details when provided', () => {
+      const error = createError(ErrorCodes.MCP.TOOL_NOT_FOUND, { tool: 'test_tool' });
+
+      expect(error.details).toEqual({ tool: 'test_tool' });
+    });
+
+    it('should use provided requestId', () => {
+      const error = createError(ErrorCodes.AUTH.REQUIRED, undefined, 'req_custom_123');
+
+      expect(error.requestId).toBe('req_custom_123');
+    });
+  });
+
+  describe('createErrorResponse', () => {
+    it('should create response with correct structure', () => {
+      const result = createErrorResponse(ErrorCodes.API_KEY.INVALID);
+
+      expect(result.status).toBe(401);
+      expect(result.response.success).toBe(false);
+      expect(result.response.error.code).toBe('VPM-API-KEY-002');
+    });
+
+    it('should use correct HTTP status codes', () => {
+      expect(createErrorResponse(ErrorCodes.AUTH.REQUIRED).status).toBe(401);
+      expect(createErrorResponse(ErrorCodes.AUTH.INSUFFICIENT_PERMISSIONS).status).toBe(403);
+      expect(createErrorResponse(ErrorCodes.MCP.TOOL_NOT_FOUND).status).toBe(404);
+      expect(createErrorResponse(ErrorCodes.API_KEY.RATE_LIMITED).status).toBe(429);
+      expect(createErrorResponse(ErrorCodes.SYSTEM.INTERNAL_ERROR).status).toBe(500);
+    });
+  });
+
+  describe('Errors helper functions', () => {
+    it('should create authRequired error', () => {
+      const result = Errors.authRequired();
+
+      expect(result.status).toBe(401);
+      expect(result.response.error.code).toBe('VPM-AUTH-001');
+    });
+
+    it('should create invalidApiKey error', () => {
+      const result = Errors.invalidApiKey();
+
+      expect(result.status).toBe(401);
+      expect(result.response.error.code).toBe('VPM-API-KEY-002');
+    });
+
+    it('should create rateLimited error with retryAfter', () => {
+      const result = Errors.rateLimited(60);
+
+      expect(result.status).toBe(429);
+      expect(result.response.error.details).toEqual({ retryAfterSeconds: 60 });
+    });
+
+    it('should create quotaExceeded error with usage details', () => {
+      const result = Errors.quotaExceeded(1000, 500);
+
+      expect(result.status).toBe(429);
+      expect(result.response.error.details?.currentUsage).toBe(1000);
+      expect(result.response.error.details?.limit).toBe(500);
+      expect(result.response.error.details?.resetDate).toBeDefined();
+    });
+
+    it('should create toolNotFound error with tool name', () => {
+      const result = Errors.toolNotFound('unknown_tool');
+
+      expect(result.status).toBe(404);
+      expect(result.response.error.details).toEqual({ tool: 'unknown_tool' });
+    });
+
+    it('should create toolExecutionFailed error', () => {
+      const result = Errors.toolExecutionFailed('test_tool', 'Connection failed');
+
+      expect(result.status).toBe(500);
+      expect(result.response.error.details).toEqual({
+        tool: 'test_tool',
+        reason: 'Connection failed',
+      });
+    });
+
+    it('should create integrationNotConnected error', () => {
+      const result = Errors.integrationNotConnected('github');
+
+      expect(result.status).toBe(400);
+      expect(result.response.error.details).toEqual({ provider: 'github' });
+    });
+
+    it('should create subscriptionRequired error', () => {
+      const result = Errors.subscriptionRequired('advanced_tools', 'pro');
+
+      expect(result.status).toBe(403);
+      expect(result.response.error.details).toEqual({
+        feature: 'advanced_tools',
+        requiredTier: 'pro',
+      });
+    });
+  });
+
+  describe('VasperaApiError', () => {
+    it('should create throwable error', () => {
+      const error = new VasperaApiError(ErrorCodes.VALIDATION.REQUIRED_FIELD, {
+        field: 'email',
+      });
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.name).toBe('VasperaApiError');
+      expect(error.message).toBe('Required field missing');
+      expect(error.errorDef).toBe(ErrorCodes.VALIDATION.REQUIRED_FIELD);
+      expect(error.details).toEqual({ field: 'email' });
+    });
+
+    it('should convert to response', () => {
+      const error = new VasperaApiError(ErrorCodes.MCP.TIMEOUT, {
+        tool: 'slow_tool',
+        timeoutMs: 30000,
+      });
+
+      const response = error.toResponse('req_test_123');
+
+      expect(response.status).toBe(504);
+      expect(response.response.error.requestId).toBe('req_test_123');
+      expect(response.response.error.details).toEqual({
+        tool: 'slow_tool',
+        timeoutMs: 30000,
+      });
+    });
+
+    it('should be catchable in try/catch', () => {
+      function throwError() {
+        throw new VasperaApiError(ErrorCodes.BILLING.NO_SUBSCRIPTION);
+      }
+
+      expect(throwError).toThrow(VasperaApiError);
+      expect(throwError).toThrow('No active subscription found');
+    });
+  });
+
+  describe('ErrorCodes structure', () => {
+    it('should have all error categories', () => {
+      expect(ErrorCodes.AUTH).toBeDefined();
+      expect(ErrorCodes.API_KEY).toBeDefined();
+      expect(ErrorCodes.MCP).toBeDefined();
+      expect(ErrorCodes.BILLING).toBeDefined();
+      expect(ErrorCodes.INTEGRATION).toBeDefined();
+      expect(ErrorCodes.VALIDATION).toBeDefined();
+      expect(ErrorCodes.SYSTEM).toBeDefined();
+    });
+
+    it('should have unique error codes', () => {
+      const allCodes = new Set<string>();
+
+      for (const category of Object.values(ErrorCodes)) {
+        for (const errorDef of Object.values(category)) {
+          if (allCodes.has(errorDef.code)) {
+            throw new Error(`Duplicate error code: ${errorDef.code}`);
+          }
+          allCodes.add(errorDef.code);
+        }
+      }
+
+      // We have at least this many unique codes
+      expect(allCodes.size).toBeGreaterThanOrEqual(25);
+    });
+  });
+});

package/src/errors/codes.ts

@@ -0,0 +1,213 @@
+export interface ErrorDefinition {
+  code: string;
+  message: string;
+  httpStatus: number;
+}
+
+export const ErrorCodes = {
+  // Authentication Errors (VPM-AUTH-XXX)
+  AUTH: {
+    REQUIRED: {
+      code: 'VPM-AUTH-001',
+      message: 'Authentication required',
+      httpStatus: 401,
+    },
+    INVALID_TOKEN: {
+      code: 'VPM-AUTH-002',
+      message: 'Invalid or expired authentication token',
+      httpStatus: 401,
+    },
+    INSUFFICIENT_PERMISSIONS: {
+      code: 'VPM-AUTH-003',
+      message: 'Insufficient permissions for this action',
+      httpStatus: 403,
+    },
+    SESSION_EXPIRED: {
+      code: 'VPM-AUTH-004',
+      message: 'Session has expired, please login again',
+      httpStatus: 401,
+    },
+    MFA_REQUIRED: {
+      code: 'VPM-AUTH-005',
+      message: 'Multi-factor authentication required',
+      httpStatus: 403,
+    },
+  },
+
+  // API Key Errors (VPM-API-KEY-XXX)
+  API_KEY: {
+    REQUIRED: {
+      code: 'VPM-API-KEY-001',
+      message: 'API key is required',
+      httpStatus: 401,
+    },
+    INVALID: {
+      code: 'VPM-API-KEY-002',
+      message: 'Invalid API key',
+      httpStatus: 401,
+    },
+    REVOKED: {
+      code: 'VPM-API-KEY-003',
+      message: 'API key has been revoked',
+      httpStatus: 401,
+    },
+    EXPIRED: {
+      code: 'VPM-API-KEY-004',
+      message: 'API key has expired',
+      httpStatus: 401,
+    },
+    RATE_LIMITED: {
+      code: 'VPM-API-KEY-005',
+      message: 'API key rate limit exceeded',
+      httpStatus: 429,
+    },
+    QUOTA_EXCEEDED: {
+      code: 'VPM-API-KEY-006',
+      message: 'Monthly usage quota exceeded',
+      httpStatus: 429,
+    },
+  },
+
+  // MCP Tool Errors (VPM-MCP-XXX)
+  MCP: {
+    TOOL_NOT_FOUND: {
+      code: 'VPM-MCP-001',
+      message: 'Requested tool not found',
+      httpStatus: 404,
+    },
+    INVALID_ARGUMENTS: {
+      code: 'VPM-MCP-002',
+      message: 'Invalid tool arguments provided',
+      httpStatus: 400,
+    },
+    EXECUTION_FAILED: {
+      code: 'VPM-MCP-003',
+      message: 'Tool execution failed',
+      httpStatus: 500,
+    },
+    TIMEOUT: {
+      code: 'VPM-MCP-004',
+      message: 'Tool execution timed out',
+      httpStatus: 504,
+    },
+    LLM_ERROR: {
+      code: 'VPM-MCP-005',
+      message: 'AI model returned an error',
+      httpStatus: 502,
+    },
+    CONTEXT_TOO_LARGE: {
+      code: 'VPM-MCP-006',
+      message: 'Input context exceeds maximum size',
+      httpStatus: 413,
+    },
+  },
+
+  // Billing Errors (VPM-BILLING-XXX)
+  BILLING: {
+    NO_SUBSCRIPTION: {
+      code: 'VPM-BILLING-001',
+      message: 'No active subscription found',
+      httpStatus: 402,
+    },
+    SUBSCRIPTION_EXPIRED: {
+      code: 'VPM-BILLING-002',
+      message: 'Subscription has expired',
+      httpStatus: 402,
+    },
+    PAYMENT_FAILED: {
+      code: 'VPM-BILLING-003',
+      message: 'Payment processing failed',
+      httpStatus: 402,
+    },
+    FEATURE_NOT_INCLUDED: {
+      code: 'VPM-BILLING-004',
+      message: 'Feature not included in current plan',
+      httpStatus: 403,
+    },
+    UPGRADE_REQUIRED: {
+      code: 'VPM-BILLING-005',
+      message: 'Plan upgrade required for this action',
+      httpStatus: 403,
+    },
+  },
+
+  // Integration Errors (VPM-INT-XXX)
+  INTEGRATION: {
+    NOT_CONNECTED: {
+      code: 'VPM-INT-001',
+      message: 'Integration not connected',
+      httpStatus: 400,
+    },
+    TOKEN_EXPIRED: {
+      code: 'VPM-INT-002',
+      message: 'Integration token expired, reconnection required',
+      httpStatus: 401,
+    },
+    REFRESH_FAILED: {
+      code: 'VPM-INT-003',
+      message: 'Failed to refresh integration token',
+      httpStatus: 502,
+    },
+    API_ERROR: {
+      code: 'VPM-INT-004',
+      message: 'External integration API error',
+      httpStatus: 502,
+    },
+    RATE_LIMITED: {
+      code: 'VPM-INT-005',
+      message: 'Integration rate limit exceeded',
+      httpStatus: 429,
+    },
+  },
+
+  // Validation Errors (VPM-VAL-XXX)
+  VALIDATION: {
+    REQUIRED_FIELD: {
+      code: 'VPM-VAL-001',
+      message: 'Required field missing',
+      httpStatus: 400,
+    },
+    INVALID_FORMAT: {
+      code: 'VPM-VAL-002',
+      message: 'Invalid field format',
+      httpStatus: 400,
+    },
+    OUT_OF_RANGE: {
+      code: 'VPM-VAL-003',
+      message: 'Value out of allowed range',
+      httpStatus: 400,
+    },
+    INVALID_JSON: {
+      code: 'VPM-VAL-004',
+      message: 'Invalid JSON in request body',
+      httpStatus: 400,
+    },
+  },
+
+  // System Errors (VPM-SYS-XXX)
+  SYSTEM: {
+    INTERNAL_ERROR: {
+      code: 'VPM-SYS-001',
+      message: 'Internal server error',
+      httpStatus: 500,
+    },
+    DATABASE_ERROR: {
+      code: 'VPM-SYS-002',
+      message: 'Database operation failed',
+      httpStatus: 500,
+    },
+    SERVICE_UNAVAILABLE: {
+      code: 'VPM-SYS-003',
+      message: 'Service temporarily unavailable',
+      httpStatus: 503,
+    },
+    MAINTENANCE_MODE: {
+      code: 'VPM-SYS-004',
+      message: 'System is under maintenance',
+      httpStatus: 503,
+    },
+  },
+} as const;
+
+export type ErrorCodeType =
+  (typeof ErrorCodes)[keyof typeof ErrorCodes][keyof (typeof ErrorCodes)[keyof typeof ErrorCodes]];

package/src/errors/factory.ts

@@ -0,0 +1,164 @@
+import type { ErrorDefinition } from './codes.js';
+import { ErrorCodes } from './codes.js';
+
+export interface VasperaError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+  timestamp: string;
+  requestId: string;
+  docUrl?: string;
+}
+
+export interface ErrorResponse {
+  success: false;
+  error: VasperaError;
+}
+
+function generateRequestId(): string {
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`;
+}
+
+export function createError(
+  errorDef: ErrorDefinition,
+  details?: Record<string, unknown>,
+  requestId?: string
+): VasperaError {
+  return {
+    code: errorDef.code,
+    message: errorDef.message,
+    details,
+    timestamp: new Date().toISOString(),
+    requestId: requestId || generateRequestId(),
+    docUrl: `https://docs.vaspera.pm/errors/${errorDef.code}`,
+  };
+}
+
+export function createErrorResponse(
+  errorDef: ErrorDefinition,
+  details?: Record<string, unknown>,
+  requestId?: string
+): { response: ErrorResponse; status: number } {
+  return {
+    response: {
+      success: false,
+      error: createError(errorDef, details, requestId),
+    },
+    status: errorDef.httpStatus,
+  };
+}
+
+function getNextResetDate(): string {
+  const now = new Date();
+  const nextMonth = new Date(now.getFullYear(), now.getMonth() + 1, 1);
+  return nextMonth.toISOString();
+}
+
+// Pre-built error creators for common cases
+export const Errors = {
+  authRequired: (requestId?: string) =>
+    createErrorResponse(ErrorCodes.AUTH.REQUIRED, undefined, requestId),
+
+  invalidApiKey: (requestId?: string) =>
+    createErrorResponse(ErrorCodes.API_KEY.INVALID, undefined, requestId),
+
+  apiKeyRevoked: (requestId?: string) =>
+    createErrorResponse(ErrorCodes.API_KEY.REVOKED, undefined, requestId),
+
+  apiKeyExpired: (requestId?: string) =>
+    createErrorResponse(ErrorCodes.API_KEY.EXPIRED, undefined, requestId),
+
+  rateLimited: (retryAfter: number, requestId?: string) =>
+    createErrorResponse(
+      ErrorCodes.API_KEY.RATE_LIMITED,
+      { retryAfterSeconds: retryAfter },
+      requestId
+    ),
+
+  quotaExceeded: (currentUsage: number, limit: number, requestId?: string) =>
+    createErrorResponse(
+      ErrorCodes.API_KEY.QUOTA_EXCEEDED,
+      { currentUsage, limit, resetDate: getNextResetDate() },
+      requestId
+    ),
+
+  toolNotFound: (toolName: string, requestId?: string) =>
+    createErrorResponse(
+      ErrorCodes.MCP.TOOL_NOT_FOUND,
+      { tool: toolName },
+      requestId
+    ),
+
+  toolExecutionFailed: (toolName: string, reason: string, requestId?: string) =>
+    createErrorResponse(
+      ErrorCodes.MCP.EXECUTION_FAILED,
+      { tool: toolName, reason },
+      requestId
+    ),
+
+  toolTimeout: (toolName: string, timeoutMs: number, requestId?: string) =>
+    createErrorResponse(
+      ErrorCodes.MCP.TIMEOUT,
+      { tool: toolName, timeoutMs },
+      requestId
+    ),
+
+  validationFailed: (field: string, reason: string, requestId?: string) =>
+    createErrorResponse(
+      ErrorCodes.VALIDATION.REQUIRED_FIELD,
+      { field, reason },
+      requestId
+    ),
+
+  invalidFormat: (field: string, expected: string, requestId?: string) =>
+    createErrorResponse(
+      ErrorCodes.VALIDATION.INVALID_FORMAT,
+      { field, expected },
+      requestId
+    ),
+
+  internalError: (message?: string, requestId?: string) =>
+    createErrorResponse(
+      ErrorCodes.SYSTEM.INTERNAL_ERROR,
+      message ? { message } : undefined,
+      requestId
+    ),
+
+  databaseError: (operation: string, requestId?: string) =>
+    createErrorResponse(
+      ErrorCodes.SYSTEM.DATABASE_ERROR,
+      { operation },
+      requestId
+    ),
+
+  integrationNotConnected: (provider: string, requestId?: string) =>
+    createErrorResponse(
+      ErrorCodes.INTEGRATION.NOT_CONNECTED,
+      { provider },
+      requestId
+    ),
+
+  subscriptionRequired: (feature: string, requiredTier: string, requestId?: string) =>
+    createErrorResponse(
+      ErrorCodes.BILLING.FEATURE_NOT_INCLUDED,
+      { feature, requiredTier },
+      requestId
+    ),
+};
+
+// Custom error class for throwing in API routes
+export class VasperaApiError extends Error {
+  public readonly errorDef: ErrorDefinition;
+  public readonly details?: Record<string, unknown>;
+
+  constructor(errorDef: ErrorDefinition, details?: Record<string, unknown>) {
+    super(errorDef.message);
+    this.name = 'VasperaApiError';
+    this.errorDef = errorDef;
+    this.details = details;
+  }
+
+  toResponse(requestId?: string): { response: ErrorResponse; status: number } {
+    return createErrorResponse(this.errorDef, this.details, requestId);
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,10 @@
+export { ErrorCodes } from './codes.js';
+export type { ErrorDefinition, ErrorCodeType } from './codes.js';
+
+export {
+  createError,
+  createErrorResponse,
+  Errors,
+  VasperaApiError,
+} from './factory.js';
+export type { VasperaError, ErrorResponse } from './factory.js';

package/src/index.ts

@@ -0,0 +1,8 @@
+// Types
+export * from './types/index.js';
+
+// Errors
+export * from './errors/index.js';
+
+// Utilities
+export * from './utils/index.js';