@rooguys/sdk 0.1.0 → 1.0.0

package/src/__tests__/property/sdk-modules.property.test.ts

@@ -0,0 +1,450 @@
+/**
+ * Property-Based Tests: Node.js SDK Modules
+ * Task 8.5: Property tests for batch validation, email validation, filter construction
+ * 
+ * Properties tested:
+ * - Property 4: Batch Event Validation (Requirements 3.1, 3.2)
+ * - Property 7: Email Validation (Requirements 4.5)
+ * - Property 10: Leaderboard Filter Query Construction (Requirements 6.1, 6.2, 6.3)
+ */
+
+import fc from 'fast-check';
+import { Rooguys } from '../../index';
+import { ValidationError } from '../../errors';
+import {
+  createMockRooguysClient,
+  mockAxiosResponse,
+  getLastRequestConfig,
+  MockAxiosInstance,
+} from '../utils/mockClient';
+
+describe('Property 4: Batch Event Validation', () => {
+  let client: Rooguys;
+  let mockAxios: MockAxiosInstance;
+
+  beforeEach(() => {
+    const mock = createMockRooguysClient();
+    client = mock.client;
+    mockAxios = mock.mockAxios;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should reject batch with more than 100 events before making API request', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        // Generate array with 101-500 events
+        fc.array(
+          fc.record({
+            eventName: fc.string({ minLength: 1, maxLength: 50 }),
+            userId: fc.string({ minLength: 1, maxLength: 50 }),
+            properties: fc.dictionary(fc.string(), fc.string()),
+          }),
+          { minLength: 101, maxLength: 500 }
+        ),
+        async (events) => {
+          // Act & Assert
+          await expect(client.events.trackBatch(events)).rejects.toThrow(ValidationError);
+          await expect(client.events.trackBatch(events)).rejects.toMatchObject({
+            code: 'BATCH_TOO_LARGE',
+          });
+          
+          // Verify no API request was made
+          expect(mockAxios.request).not.toHaveBeenCalled();
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should accept batch with 1-100 events and make exactly one API request', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        // Generate array with 1-100 events
+        fc.array(
+          fc.record({
+            eventName: fc.string({ minLength: 1, maxLength: 50 }),
+            userId: fc.string({ minLength: 1, maxLength: 50 }),
+            properties: fc.dictionary(fc.string(), fc.string()),
+          }),
+          { minLength: 1, maxLength: 100 }
+        ),
+        async (events) => {
+          // Reset mock before each iteration
+          mockAxios.request.mockReset();
+          mockAxios.request.mockResolvedValue(mockAxiosResponse({
+            results: events.map((_, index) => ({ index, status: 'queued' })),
+          }));
+
+          // Act
+          await client.events.trackBatch(events);
+
+          // Assert - exactly one API request was made
+          expect(mockAxios.request).toHaveBeenCalledTimes(1);
+          
+          // Verify request was to batch endpoint
+          const config = getLastRequestConfig(mockAxios);
+          expect(config.url).toBe('/events/batch');
+          expect(config.method).toBe('POST');
+          expect(config.data.events).toHaveLength(events.length);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should reject empty batch before making API request', async () => {
+    // Act & Assert
+    await expect(client.events.trackBatch([])).rejects.toThrow(ValidationError);
+    await expect(client.events.trackBatch([])).rejects.toMatchObject({
+      code: 'EMPTY_EVENTS',
+    });
+    
+    // Verify no API request was made
+    expect(mockAxios.request).not.toHaveBeenCalled();
+  });
+});
+
+describe('Property 7: Email Validation', () => {
+  let client: Rooguys;
+  let mockAxios: MockAxiosInstance;
+
+  beforeEach(() => {
+    const mock = createMockRooguysClient();
+    client = mock.client;
+    mockAxios = mock.mockAxios;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should reject invalid email formats before making API request (user create)', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 1, maxLength: 50 }), // userId
+        // Generate invalid emails (no @ or no domain)
+        fc.oneof(
+          fc.string({ minLength: 1, maxLength: 50 }).filter(s => !s.includes('@')),
+          fc.string({ minLength: 1, maxLength: 50 }).map(s => `${s}@`),
+          fc.string({ minLength: 1, maxLength: 50 }).map(s => `@${s}`),
+          fc.constant('invalid'),
+          fc.constant('no-at-sign'),
+          fc.constant('@nodomain'),
+          fc.constant('missing@'),
+        ),
+        async (userId, invalidEmail) => {
+          // Act & Assert
+          await expect(client.users.create({ userId, email: invalidEmail })).rejects.toThrow(ValidationError);
+          await expect(client.users.create({ userId, email: invalidEmail })).rejects.toMatchObject({
+            code: 'INVALID_EMAIL',
+          });
+          
+          // Verify no API request was made
+          expect(mockAxios.request).not.toHaveBeenCalled();
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should reject invalid email formats before making API request (user update)', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 1, maxLength: 50 }), // userId
+        // Generate invalid emails
+        fc.oneof(
+          fc.string({ minLength: 1, maxLength: 50 }).filter(s => !s.includes('@')),
+          fc.string({ minLength: 1, maxLength: 50 }).map(s => `${s}@`),
+          fc.constant('invalid'),
+          fc.constant('no-at-sign'),
+        ),
+        async (userId, invalidEmail) => {
+          // Act & Assert
+          await expect(client.users.update(userId, { email: invalidEmail })).rejects.toThrow(ValidationError);
+          await expect(client.users.update(userId, { email: invalidEmail })).rejects.toMatchObject({
+            code: 'INVALID_EMAIL',
+          });
+          
+          // Verify no API request was made
+          expect(mockAxios.request).not.toHaveBeenCalled();
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should accept valid email formats and make API request', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 1, maxLength: 50 }), // userId
+        // Generate valid emails
+        fc.tuple(
+          fc.string({ minLength: 1, maxLength: 20 }).filter(s => /^[a-zA-Z0-9._-]+$/.test(s)),
+          fc.string({ minLength: 1, maxLength: 20 }).filter(s => /^[a-zA-Z0-9.-]+$/.test(s)),
+          fc.constantFrom('com', 'org', 'net', 'io', 'co.uk')
+        ).map(([local, domain, tld]) => `${local}@${domain}.${tld}`),
+        async (userId, validEmail) => {
+          // Reset mock before each iteration
+          mockAxios.request.mockReset();
+          mockAxios.request.mockResolvedValue(mockAxiosResponse({
+            user_id: userId,
+            email: validEmail,
+            points: 0,
+          }));
+
+          // Act
+          await client.users.create({ userId, email: validEmail });
+
+          // Assert - API request was made
+          expect(mockAxios.request).toHaveBeenCalledTimes(1);
+          
+          const config = getLastRequestConfig(mockAxios);
+          expect(config.data.email).toBe(validEmail);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should allow user creation without email', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 1, maxLength: 50 }), // userId
+        async (userId) => {
+          // Reset mock before each iteration
+          mockAxios.request.mockReset();
+          mockAxios.request.mockResolvedValue(mockAxiosResponse({
+            user_id: userId,
+            points: 0,
+          }));
+
+          // Act
+          await client.users.create({ userId });
+
+          // Assert - API request was made
+          expect(mockAxios.request).toHaveBeenCalledTimes(1);
+          
+          const config = getLastRequestConfig(mockAxios);
+          expect(config.data.user_id).toBe(userId);
+          expect(config.data.email).toBeUndefined();
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+});
+
+describe('Property 10: Leaderboard Filter Query Construction', () => {
+  let client: Rooguys;
+  let mockAxios: MockAxiosInstance;
+
+  beforeEach(() => {
+    const mock = createMockRooguysClient();
+    client = mock.client;
+    mockAxios = mock.mockAxios;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should include persona filter in query parameters', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.constantFrom('Competitor', 'Explorer', 'Achiever', 'Socializer'),
+        async (persona) => {
+          // Arrange
+          mockAxios.request.mockResolvedValue(mockAxiosResponse({
+            rankings: [],
+            page: 1,
+            limit: 50,
+            total: 0,
+          }));
+
+          // Act
+          await client.leaderboards.getGlobal({ persona });
+
+          // Assert
+          const config = getLastRequestConfig(mockAxios);
+          expect(config.params.persona).toBe(persona);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should include level range filters in query parameters', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.integer({ min: 1, max: 50 }),
+        fc.integer({ min: 51, max: 100 }),
+        async (minLevel, maxLevel) => {
+          // Arrange
+          mockAxios.request.mockResolvedValue(mockAxiosResponse({
+            rankings: [],
+            page: 1,
+            limit: 50,
+            total: 0,
+          }));
+
+          // Act
+          await client.leaderboards.getGlobal({ minLevel, maxLevel });
+
+          // Assert
+          const config = getLastRequestConfig(mockAxios);
+          expect(config.params.min_level).toBe(minLevel);
+          expect(config.params.max_level).toBe(maxLevel);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should format date filters as ISO 8601 strings', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.date({ min: new Date('2020-01-01'), max: new Date('2025-12-31') }),
+        fc.date({ min: new Date('2020-01-01'), max: new Date('2025-12-31') }),
+        async (startDate, endDate) => {
+          // Arrange
+          mockAxios.request.mockResolvedValue(mockAxiosResponse({
+            rankings: [],
+            page: 1,
+            limit: 50,
+            total: 0,
+          }));
+
+          // Act
+          await client.leaderboards.getGlobal({ startDate, endDate });
+
+          // Assert
+          const config = getLastRequestConfig(mockAxios);
+          
+          // Verify dates are ISO 8601 formatted
+          expect(config.params.start_date).toBe(startDate.toISOString());
+          expect(config.params.end_date).toBe(endDate.toISOString());
+          
+          // Verify ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ)
+          expect(config.params.start_date).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/);
+          expect(config.params.end_date).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should include all filter parameters when provided together', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.record({
+          persona: fc.constantFrom('Competitor', 'Explorer', 'Achiever', 'Socializer'),
+          minLevel: fc.integer({ min: 1, max: 50 }),
+          maxLevel: fc.integer({ min: 51, max: 100 }),
+          startDate: fc.date({ min: new Date('2020-01-01'), max: new Date('2023-12-31') }),
+          endDate: fc.date({ min: new Date('2024-01-01'), max: new Date('2025-12-31') }),
+          page: fc.integer({ min: 1, max: 100 }),
+          limit: fc.integer({ min: 1, max: 100 }),
+        }),
+        async (filters) => {
+          // Arrange
+          mockAxios.request.mockResolvedValue(mockAxiosResponse({
+            rankings: [],
+            page: filters.page,
+            limit: filters.limit,
+            total: 0,
+          }));
+
+          // Act
+          await client.leaderboards.getGlobal(filters);
+
+          // Assert
+          const config = getLastRequestConfig(mockAxios);
+          expect(config.params.persona).toBe(filters.persona);
+          expect(config.params.min_level).toBe(filters.minLevel);
+          expect(config.params.max_level).toBe(filters.maxLevel);
+          expect(config.params.start_date).toBe(filters.startDate.toISOString());
+          expect(config.params.end_date).toBe(filters.endDate.toISOString());
+          expect(config.params.page).toBe(filters.page);
+          expect(config.params.limit).toBe(filters.limit);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should work with custom leaderboard endpoint with filters', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.uuid(),
+        fc.record({
+          persona: fc.option(fc.constantFrom('Competitor', 'Explorer', 'Achiever', 'Socializer'), { nil: undefined }),
+          minLevel: fc.option(fc.integer({ min: 1, max: 50 }), { nil: undefined }),
+          maxLevel: fc.option(fc.integer({ min: 51, max: 100 }), { nil: undefined }),
+        }),
+        async (leaderboardId, filters) => {
+          // Arrange
+          mockAxios.request.mockResolvedValue(mockAxiosResponse({
+            rankings: [],
+            page: 1,
+            limit: 50,
+            total: 0,
+          }));
+
+          // Act
+          await client.leaderboards.getCustom(leaderboardId, filters);
+
+          // Assert
+          const config = getLastRequestConfig(mockAxios);
+          expect(config.url).toBe(`/leaderboards/${encodeURIComponent(leaderboardId)}`);
+          
+          // Verify only provided filters are included
+          if (filters.persona !== undefined) {
+            expect(config.params.persona).toBe(filters.persona);
+          }
+          if (filters.minLevel !== undefined) {
+            expect(config.params.min_level).toBe(filters.minLevel);
+          }
+          if (filters.maxLevel !== undefined) {
+            expect(config.params.max_level).toBe(filters.maxLevel);
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should not include undefined filter parameters', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.constantFrom('all-time', 'weekly', 'monthly'),
+        async (timeframe) => {
+          // Arrange
+          mockAxios.request.mockResolvedValue(mockAxiosResponse({
+            rankings: [],
+            page: 1,
+            limit: 50,
+            total: 0,
+          }));
+
+          // Act - call with no filters
+          await client.leaderboards.getGlobal({ timeframe: timeframe as any });
+
+          // Assert
+          const config = getLastRequestConfig(mockAxios);
+          expect(config.params.timeframe).toBe(timeframe);
+          
+          // Verify undefined filters are not included
+          expect(config.params.persona).toBeUndefined();
+          expect(config.params.min_level).toBeUndefined();
+          expect(config.params.max_level).toBeUndefined();
+          expect(config.params.start_date).toBeUndefined();
+          expect(config.params.end_date).toBeUndefined();
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+});

package/src/__tests__/unit/aha.test.ts

@@ -1,50 +1,60 @@
 import { Rooguys } from '../../index';
-import { createMockAxiosInstance } from '../utils/mockClient';
+import {
+  createMockRooguysClient,
+  setupMockRequest,
+  setupMockRequestError,
+  expectRequestWith,
+  MockAxiosInstance,
+} from '../utils/mockClient';
 import { mockResponses, mockErrors } from '../fixtures/responses';
 
 describe('Aha Resource', () => {
   let client: Rooguys;
-  let mockAxios: any;
+  let mockAxios: MockAxiosInstance;
 
   beforeEach(() => {
-    mockAxios = createMockAxiosInstance();
-    client = new Rooguys('test-api-key');
-    (client as any).client = mockAxios;
+    const mock = createMockRooguysClient();
+    client = mock.client;
+    mockAxios = mock.mockAxios;
   });
 
   describe('declare', () => {
     it('should declare aha score with valid value', async () => {
-      mockAxios.post.mockResolvedValue({ data: mockResponses.ahaDeclarationResponse });
+      setupMockRequest(mockAxios, mockResponses.ahaDeclarationResponse);
 
       const result = await client.aha.declare('user123', 4);
 
-      expect(mockAxios.post).toHaveBeenCalledWith('/aha/declare', {
-        user_id: 'user123',
-        value: 4,
+      expectRequestWith(mockAxios, {
+        method: 'POST',
+        url: '/aha/declare',
+        data: { user_id: 'user123', value: 4 },
       });
+      // SDK returns the full response since there's no data field to unwrap
       expect(result).toEqual(mockResponses.ahaDeclarationResponse);
     });
 
     it('should declare aha score with value 1', async () => {
-      mockAxios.post.mockResolvedValue({ data: mockResponses.ahaDeclarationResponse });
+      setupMockRequest(mockAxios, mockResponses.ahaDeclarationResponse);
 
       const result = await client.aha.declare('user123', 1);
 
-      expect(mockAxios.post).toHaveBeenCalledWith('/aha/declare', {
-        user_id: 'user123',
-        value: 1,
+      expectRequestWith(mockAxios, {
+        method: 'POST',
+        url: '/aha/declare',
+        data: { user_id: 'user123', value: 1 },
       });
       expect(result).toEqual(mockResponses.ahaDeclarationResponse);
     });
 
     it('should declare aha score with value 5', async () => {
-      mockAxios.post.mockResolvedValue({ data: mockResponses.ahaDeclarationResponse });
+      setupMockRequest(mockAxios, mockResponses.ahaDeclarationResponse);
 
       const result = await client.aha.declare('user123', 5);
 
-      expect(mockAxios.post).toHaveBeenCalledWith('/aha/declare', {
-        user_id: 'user123',
-        value: 5,
+      expectRequestWith(mockAxios, {
+        method: 'POST',
+        url: '/aha/declare',
+        data: { user_id: 'user123', value: 5 },
       });
       expect(result).toEqual(mockResponses.ahaDeclarationResponse);
     });
@@ -53,37 +63,34 @@ describe('Aha Resource', () => {
       await expect(client.aha.declare('user123', 0)).rejects.toThrow(
         'Aha score value must be an integer between 1 and 5'
       );
-      expect(mockAxios.post).not.toHaveBeenCalled();
+      expect(mockAxios.request).not.toHaveBeenCalled();
     });
 
     it('should throw error for value 6', async () => {
       await expect(client.aha.declare('user123', 6)).rejects.toThrow(
         'Aha score value must be an integer between 1 and 5'
       );
-      expect(mockAxios.post).not.toHaveBeenCalled();
+      expect(mockAxios.request).not.toHaveBeenCalled();
     });
 
     it('should throw error for negative value', async () => {
       await expect(client.aha.declare('user123', -1)).rejects.toThrow(
         'Aha score value must be an integer between 1 and 5'
       );
-      expect(mockAxios.post).not.toHaveBeenCalled();
+      expect(mockAxios.request).not.toHaveBeenCalled();
     });
 
     it('should throw error for non-integer value', async () => {
       await expect(client.aha.declare('user123', 3.5)).rejects.toThrow(
         'Aha score value must be an integer between 1 and 5'
       );
-      expect(mockAxios.post).not.toHaveBeenCalled();
+      expect(mockAxios.request).not.toHaveBeenCalled();
     });
 
     it('should handle API error response', async () => {
-      mockAxios.post.mockRejectedValue({
-        isAxiosError: true,
-        response: {
-          data: mockErrors.ahaValueError,
-        },
-      });
+      setupMockRequestError(mockAxios, 400, 'Validation failed', 'VALIDATION_ERROR', [
+        { field: 'value', message: 'value must be an integer between 1 and 5' },
+      ]);
 
       await expect(client.aha.declare('user123', 3)).rejects.toThrow();
     });
@@ -91,33 +98,41 @@ describe('Aha Resource', () => {
 
   describe('getUserScore', () => {
     it('should get user aha score successfully', async () => {
-      mockAxios.get.mockResolvedValue({ data: mockResponses.ahaScoreResponse });
+      // The API returns { success: true, data: {...} } and SDK unwraps to just data
+      // So we mock the wrapped response but expect the unwrapped data
+      setupMockRequest(mockAxios, mockResponses.ahaScoreResponse);
 
       const result = await client.aha.getUserScore('user123');
 
-      expect(mockAxios.get).toHaveBeenCalledWith('/users/user123/aha');
-      expect(result).toEqual(mockResponses.ahaScoreResponse);
+      expectRequestWith(mockAxios, {
+        method: 'GET',
+        url: '/users/user123/aha',
+      });
+      // SDK unwraps { success: true, data: {...} } to just the data part
+      // Cast to any since the type expects the wrapper but we get unwrapped data
+      expect((result as any).user_id).toBe('user123');
     });
 
     it('should parse all aha score fields correctly', async () => {
-      mockAxios.get.mockResolvedValue({ data: mockResponses.ahaScoreResponse });
+      setupMockRequest(mockAxios, mockResponses.ahaScoreResponse);
 
       const result = await client.aha.getUserScore('user123');
 
-      expect(result.success).toBe(true);
-      expect(result.data.user_id).toBe('user123');
-      expect(result.data.current_score).toBe(75);
-      expect(result.data.declarative_score).toBe(80);
-      expect(result.data.inferred_score).toBe(70);
-      expect(result.data.status).toBe('activated');
+      // Result is the unwrapped data (cast to any to access fields)
+      const data = result as any;
+      expect(data.user_id).toBe('user123');
+      expect(data.current_score).toBe(75);
+      expect(data.declarative_score).toBe(80);
+      expect(data.inferred_score).toBe(70);
+      expect(data.status).toBe('activated');
     });
 
     it('should preserve history structure', async () => {
-      mockAxios.get.mockResolvedValue({ data: mockResponses.ahaScoreResponse });
+      setupMockRequest(mockAxios, mockResponses.ahaScoreResponse);
 
       const result = await client.aha.getUserScore('user123');
 
-      expect(result.data.history).toEqual({
+      expect((result as any).history).toEqual({
         initial: 50,
         initial_date: '2024-01-01T00:00:00Z',
         previous: 70,
@@ -125,13 +140,7 @@ describe('Aha Resource', () => {
     });
 
     it('should handle 404 error when user not found', async () => {
-      mockAxios.get.mockRejectedValue({
-        isAxiosError: true,
-        response: {
-          status: 404,
-          data: mockErrors.notFoundError,
-        },
-      });
+      setupMockRequestError(mockAxios, 404, 'User not found', 'NOT_FOUND');
 
       await expect(client.aha.getUserScore('nonexistent')).rejects.toThrow();
     });
@@ -152,13 +161,15 @@ describe('Aha Resource', () => {
           },
         },
       };
-      mockAxios.get.mockResolvedValue({ data: responseWithNulls });
+      setupMockRequest(mockAxios, responseWithNulls);
 
       const result = await client.aha.getUserScore('user123');
 
-      expect(result.data.declarative_score).toBeNull();
-      expect(result.data.inferred_score).toBeNull();
-      expect(result.data.history.initial).toBeNull();
+      // Result is the unwrapped data
+      const data = result as any;
+      expect(data.declarative_score).toBeNull();
+      expect(data.inferred_score).toBeNull();
+      expect(data.history.initial).toBeNull();
     });
   });
 });