@rooguys/js 0.1.0 → 1.0.0

package/src/__tests__/property/error-mapping.property.test.js

@@ -0,0 +1,506 @@
+/**
+ * Property-Based Test: Error Response Mapping
+ * Feature: sdk-documentation-update, Property 3: Error Response Mapping
+ * Validates: Requirements 2.2, 8.1, 8.2, 8.4
+ * 
+ * Tests that any API error response with HTTP status code and error body
+ * is mapped to the correct typed error (ValidationError for 400, AuthenticationError for 401,
+ * NotFoundError for 404, ConflictError for 409, RateLimitError for 429, ServerError for 500)
+ * with the error code and request ID preserved.
+ */
+
+import fc from 'fast-check';
+import { jest } from '@jest/globals';
+import Rooguys, {
+  RooguysError,
+  ValidationError,
+  AuthenticationError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  RateLimitError,
+  ServerError,
+  mapStatusToError,
+} from '../../index.js';
+import { createMockFetch, createMockHeaders, mockErrorResponse } from '../utils/mockClient.js';
+import { arbitraries } from '../utils/generators.js';
+
+describe('Property 3: Error Response Mapping', () => {
+  let mockFetch;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+    global.fetch = mockFetch;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('mapStatusToError', () => {
+    it('should map HTTP 400 to ValidationError', () => {
+      fc.assert(
+        fc.property(
+          fc.string({ minLength: 5, maxLength: 100 }),
+          fc.constantFrom('VALIDATION_ERROR', 'INVALID_INPUT', 'MISSING_FIELD'),
+          arbitraries.requestId(),
+          fc.option(
+            fc.array(
+              fc.record({
+                field: fc.string({ minLength: 1, maxLength: 30 }),
+                message: fc.string({ minLength: 5, maxLength: 100 }),
+              }),
+              { minLength: 1, maxLength: 5 }
+            ),
+            { nil: null }
+          ),
+          (message, code, requestId, fieldErrors) => {
+            // Arrange
+            const errorBody = {
+              error: { code, message, details: fieldErrors },
+            };
+
+            // Act
+            const error = mapStatusToError(400, errorBody, requestId, {});
+
+            // Assert
+            expect(error).toBeInstanceOf(ValidationError);
+            expect(error.statusCode).toBe(400);
+            expect(error.message).toBe(message);
+            expect(error.code).toBe(code);
+            expect(error.requestId).toBe(requestId);
+            expect(error.fieldErrors).toEqual(fieldErrors);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should map HTTP 401 to AuthenticationError', () => {
+      fc.assert(
+        fc.property(
+          fc.string({ minLength: 5, maxLength: 100 }),
+          fc.constantFrom('INVALID_API_KEY', 'MISSING_API_KEY', 'EXPIRED_TOKEN'),
+          arbitraries.requestId(),
+          (message, code, requestId) => {
+            // Arrange
+            const errorBody = { error: { code, message } };
+
+            // Act
+            const error = mapStatusToError(401, errorBody, requestId, {});
+
+            // Assert
+            expect(error).toBeInstanceOf(AuthenticationError);
+            expect(error.statusCode).toBe(401);
+            expect(error.message).toBe(message);
+            expect(error.code).toBe(code);
+            expect(error.requestId).toBe(requestId);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should map HTTP 403 to ForbiddenError', () => {
+      fc.assert(
+        fc.property(
+          fc.string({ minLength: 5, maxLength: 100 }),
+          fc.constantFrom('FORBIDDEN', 'ACCESS_DENIED', 'INSUFFICIENT_PERMISSIONS'),
+          arbitraries.requestId(),
+          (message, code, requestId) => {
+            // Arrange
+            const errorBody = { error: { code, message } };
+
+            // Act
+            const error = mapStatusToError(403, errorBody, requestId, {});
+
+            // Assert
+            expect(error).toBeInstanceOf(ForbiddenError);
+            expect(error.statusCode).toBe(403);
+            expect(error.message).toBe(message);
+            expect(error.code).toBe(code);
+            expect(error.requestId).toBe(requestId);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should map HTTP 404 to NotFoundError', () => {
+      fc.assert(
+        fc.property(
+          fc.string({ minLength: 5, maxLength: 100 }),
+          fc.constantFrom('NOT_FOUND', 'USER_NOT_FOUND', 'RESOURCE_NOT_FOUND'),
+          arbitraries.requestId(),
+          (message, code, requestId) => {
+            // Arrange
+            const errorBody = { error: { code, message } };
+
+            // Act
+            const error = mapStatusToError(404, errorBody, requestId, {});
+
+            // Assert
+            expect(error).toBeInstanceOf(NotFoundError);
+            expect(error.statusCode).toBe(404);
+            expect(error.message).toBe(message);
+            expect(error.code).toBe(code);
+            expect(error.requestId).toBe(requestId);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should map HTTP 409 to ConflictError', () => {
+      fc.assert(
+        fc.property(
+          fc.string({ minLength: 5, maxLength: 100 }),
+          fc.constantFrom('CONFLICT', 'USER_EXISTS', 'DUPLICATE_ENTRY'),
+          arbitraries.requestId(),
+          (message, code, requestId) => {
+            // Arrange
+            const errorBody = { error: { code, message } };
+
+            // Act
+            const error = mapStatusToError(409, errorBody, requestId, {});
+
+            // Assert
+            expect(error).toBeInstanceOf(ConflictError);
+            expect(error.statusCode).toBe(409);
+            expect(error.message).toBe(message);
+            expect(error.code).toBe(code);
+            expect(error.requestId).toBe(requestId);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should map HTTP 429 to RateLimitError with retryAfter', () => {
+      fc.assert(
+        fc.property(
+          fc.string({ minLength: 5, maxLength: 100 }),
+          fc.constantFrom('RATE_LIMIT_EXCEEDED', 'TOO_MANY_REQUESTS'),
+          arbitraries.requestId(),
+          fc.integer({ min: 1, max: 3600 }),
+          (message, code, requestId, retryAfter) => {
+            // Arrange
+            const errorBody = { error: { code, message } };
+            const headers = { 'retry-after': String(retryAfter) };
+
+            // Act
+            const error = mapStatusToError(429, errorBody, requestId, headers);
+
+            // Assert
+            expect(error).toBeInstanceOf(RateLimitError);
+            expect(error.statusCode).toBe(429);
+            expect(error.message).toBe(message);
+            expect(error.code).toBe(code);
+            expect(error.requestId).toBe(requestId);
+            expect(error.retryAfter).toBe(retryAfter);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should map HTTP 500+ to ServerError', () => {
+      fc.assert(
+        fc.property(
+          fc.constantFrom(500, 502, 503, 504),
+          fc.string({ minLength: 5, maxLength: 100 }),
+          fc.constantFrom('INTERNAL_ERROR', 'SERVER_ERROR', 'SERVICE_UNAVAILABLE'),
+          arbitraries.requestId(),
+          (status, message, code, requestId) => {
+            // Arrange
+            const errorBody = { error: { code, message } };
+
+            // Act
+            const error = mapStatusToError(status, errorBody, requestId, {});
+
+            // Assert
+            expect(error).toBeInstanceOf(ServerError);
+            expect(error.statusCode).toBe(status);
+            expect(error.message).toBe(message);
+            expect(error.code).toBe(code);
+            expect(error.requestId).toBe(requestId);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should preserve requestId in all error types', () => {
+      fc.assert(
+        fc.property(
+          arbitraries.errorCodeStatusPair(),
+          fc.string({ minLength: 5, maxLength: 100 }),
+          arbitraries.requestId(),
+          ({ code, status }, message, requestId) => {
+            // Arrange
+            const errorBody = { error: { code, message } };
+            const headers = status === 429 ? { 'retry-after': '60' } : {};
+
+            // Act
+            const error = mapStatusToError(status, errorBody, requestId, headers);
+
+            // Assert
+            expect(error.requestId).toBe(requestId);
+            expect(error.code).toBe(code);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should handle legacy error format (error as string)', () => {
+      fc.assert(
+        fc.property(
+          fc.constantFrom(400, 401, 404, 500),
+          fc.string({ minLength: 5, maxLength: 100 }),
+          arbitraries.requestId(),
+          (status, message, requestId) => {
+            // Arrange - legacy format with error as string
+            const errorBody = { error: message };
+
+            // Act
+            const error = mapStatusToError(status, errorBody, requestId, {});
+
+            // Assert
+            expect(error).toBeInstanceOf(RooguysError);
+            expect(error.message).toBe(message);
+            expect(error.requestId).toBe(requestId);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('SDK error handling integration', () => {
+    it('should throw correct error type for API errors', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          arbitraries.apiKey(),
+          arbitraries.userId(),
+          fc.constantFrom(
+            { status: 400, ErrorClass: ValidationError },
+            { status: 401, ErrorClass: AuthenticationError },
+            { status: 403, ErrorClass: ForbiddenError },
+            { status: 404, ErrorClass: NotFoundError },
+            { status: 409, ErrorClass: ConflictError },
+            { status: 429, ErrorClass: RateLimitError },
+            { status: 500, ErrorClass: ServerError }
+          ),
+          fc.string({ minLength: 5, maxLength: 100 }),
+          arbitraries.requestId(),
+          async (apiKey, userId, { status, ErrorClass }, message, requestId) => {
+            // Arrange
+            mockFetch.mockClear();
+            const errorResponse = {
+              success: false,
+              error: {
+                code: `ERROR_${status}`,
+                message,
+              },
+              request_id: requestId,
+            };
+            mockFetch.mockResolvedValue({
+              ok: false,
+              status,
+              statusText: message,
+              headers: createMockHeaders({
+                'X-Request-Id': requestId,
+                'Retry-After': '60',
+              }),
+              json: async () => errorResponse,
+            });
+            const sdk = new Rooguys(apiKey);
+
+            // Act & Assert
+            try {
+              await sdk.users.get(userId);
+              // Should not reach here
+              expect(true).toBe(false);
+            } catch (error) {
+              expect(error).toBeInstanceOf(ErrorClass);
+              expect(error.requestId).toBe(requestId);
+              expect(error.statusCode).toBe(status);
+            }
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should include field errors in ValidationError', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          arbitraries.apiKey(),
+          arbitraries.userId(),
+          fc.array(
+            fc.record({
+              field: fc.string({ minLength: 1, maxLength: 30 }),
+              message: fc.string({ minLength: 5, maxLength: 100 }),
+            }),
+            { minLength: 1, maxLength: 5 }
+          ),
+          arbitraries.requestId(),
+          async (apiKey, userId, fieldErrors, requestId) => {
+            // Arrange
+            mockFetch.mockClear();
+            const errorResponse = {
+              success: false,
+              error: {
+                code: 'VALIDATION_ERROR',
+                message: 'Validation failed',
+                details: fieldErrors,
+              },
+              request_id: requestId,
+            };
+            mockFetch.mockResolvedValue({
+              ok: false,
+              status: 400,
+              statusText: 'Bad Request',
+              headers: createMockHeaders({ 'X-Request-Id': requestId }),
+              json: async () => errorResponse,
+            });
+            const sdk = new Rooguys(apiKey);
+
+            // Act & Assert
+            try {
+              await sdk.users.get(userId);
+              expect(true).toBe(false);
+            } catch (error) {
+              expect(error).toBeInstanceOf(ValidationError);
+              expect(error.fieldErrors).toEqual(fieldErrors);
+            }
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should include retryAfter in RateLimitError', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          arbitraries.apiKey(),
+          arbitraries.userId(),
+          fc.integer({ min: 1, max: 3600 }),
+          arbitraries.requestId(),
+          async (apiKey, userId, retryAfter, requestId) => {
+            // Arrange
+            mockFetch.mockClear();
+            const errorResponse = {
+              success: false,
+              error: {
+                code: 'RATE_LIMIT_EXCEEDED',
+                message: 'Rate limit exceeded',
+              },
+              request_id: requestId,
+            };
+            mockFetch.mockResolvedValue({
+              ok: false,
+              status: 429,
+              statusText: 'Too Many Requests',
+              headers: createMockHeaders({
+                'X-Request-Id': requestId,
+                'Retry-After': String(retryAfter),
+              }),
+              json: async () => errorResponse,
+            });
+            const sdk = new Rooguys(apiKey);
+
+            // Act & Assert
+            try {
+              await sdk.users.get(userId);
+              expect(true).toBe(false);
+            } catch (error) {
+              expect(error).toBeInstanceOf(RateLimitError);
+              expect(error.retryAfter).toBe(retryAfter);
+            }
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('Error serialization', () => {
+    it('should serialize errors to JSON with all properties', () => {
+      fc.assert(
+        fc.property(
+          fc.string({ minLength: 5, maxLength: 100 }),
+          fc.constantFrom('VALIDATION_ERROR', 'NOT_FOUND', 'SERVER_ERROR'),
+          arbitraries.requestId(),
+          fc.constantFrom(400, 404, 500),
+          (message, code, requestId, statusCode) => {
+            // Arrange
+            const error = new RooguysError(message, { code, requestId, statusCode });
+
+            // Act
+            const json = error.toJSON();
+
+            // Assert
+            expect(json.name).toBe('RooguysError');
+            expect(json.message).toBe(message);
+            expect(json.code).toBe(code);
+            expect(json.requestId).toBe(requestId);
+            expect(json.statusCode).toBe(statusCode);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should serialize ValidationError with fieldErrors', () => {
+      fc.assert(
+        fc.property(
+          fc.string({ minLength: 5, maxLength: 100 }),
+          arbitraries.requestId(),
+          fc.array(
+            fc.record({
+              field: fc.string({ minLength: 1, maxLength: 30 }),
+              message: fc.string({ minLength: 5, maxLength: 100 }),
+            }),
+            { minLength: 1, maxLength: 5 }
+          ),
+          (message, requestId, fieldErrors) => {
+            // Arrange
+            const error = new ValidationError(message, { requestId, fieldErrors });
+
+            // Act
+            const json = error.toJSON();
+
+            // Assert
+            expect(json.name).toBe('ValidationError');
+            expect(json.fieldErrors).toEqual(fieldErrors);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should serialize RateLimitError with retryAfter', () => {
+      fc.assert(
+        fc.property(
+          fc.string({ minLength: 5, maxLength: 100 }),
+          arbitraries.requestId(),
+          fc.integer({ min: 1, max: 3600 }),
+          (message, requestId, retryAfter) => {
+            // Arrange
+            const error = new RateLimitError(message, { requestId, retryAfter });
+
+            // Act
+            const json = error.toJSON();
+
+            // Assert
+            expect(json.name).toBe('RateLimitError');
+            expect(json.retryAfter).toBe(retryAfter);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+});