@rooguys/js 0.1.0 → 1.0.0

package/src/__tests__/property/timestamp-validation.property.test.js

@@ -0,0 +1,345 @@
+/**
+ * Property-Based Test: Timestamp Validation
+ * Feature: sdk-documentation-update, Property 5: Timestamp Validation
+ * Validates: Requirements 3.5, 3.6
+ * 
+ * For any custom timestamp provided to event tracking methods, if the timestamp
+ * is more than 7 days in the past, the SDK SHALL throw a ValidationError with
+ * code TIMESTAMP_TOO_OLD. If the timestamp is within 7 days, it SHALL be
+ * included in the request body.
+ */
+
+import fc from 'fast-check';
+import { jest } from '@jest/globals';
+import Rooguys, { ValidationError } from '../../index.js';
+import { createMockFetch, createMockHeaders } from '../utils/mockClient.js';
+
+describe('Property 5: Timestamp Validation', () => {
+  let mockFetch;
+  const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+    global.fetch = mockFetch;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const createSuccessResponse = () => ({
+    ok: true,
+    headers: createMockHeaders({
+      'X-RateLimit-Limit': '1000',
+      'X-RateLimit-Remaining': '950',
+      'X-RateLimit-Reset': '1704067200',
+    }),
+    json: async () => ({
+      success: true,
+      data: { status: 'queued', message: 'Event accepted for processing' },
+    }),
+  });
+
+  const createBatchSuccessResponse = (count) => ({
+    ok: true,
+    headers: createMockHeaders({
+      'X-RateLimit-Limit': '1000',
+      'X-RateLimit-Remaining': '950',
+      'X-RateLimit-Reset': '1704067200',
+    }),
+    json: async () => ({
+      success: true,
+      data: {
+        results: Array.from({ length: count }, (_, i) => ({ index: i, status: 'queued' })),
+      },
+    }),
+  });
+
+  // Generator for timestamps older than 7 days
+  const oldTimestamp = () => fc.integer({ min: 8, max: 365 }).map(daysAgo => 
+    new Date(Date.now() - daysAgo * 24 * 60 * 60 * 1000)
+  );
+
+  // Generator for timestamps within 7 days (valid)
+  const validTimestamp = () => fc.integer({ min: 0, max: 6 }).chain(daysAgo =>
+    fc.integer({ min: 0, max: 23 }).chain(hours =>
+      fc.integer({ min: 0, max: 59 }).map(minutes => {
+        const ms = daysAgo * 24 * 60 * 60 * 1000 + hours * 60 * 60 * 1000 + minutes * 60 * 1000;
+        return new Date(Date.now() - ms);
+      })
+    )
+  );
+
+  describe('Single Event Tracking (track)', () => {
+    it('should throw ValidationError with TIMESTAMP_TOO_OLD for timestamps older than 7 days', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.string({ minLength: 1, maxLength: 100 }).filter(s => s.trim().length > 0), // Event name
+          fc.string({ minLength: 1, maxLength: 255 }).filter(s => s.trim().length > 0), // User ID
+          oldTimestamp(),
+          async (apiKey, eventName, userId, timestamp) => {
+            // Arrange
+            mockFetch.mockClear();
+            const sdk = new Rooguys(apiKey);
+
+            // Act & Assert
+            try {
+              await sdk.events.track(eventName, userId, {}, { timestamp });
+              // Should not reach here
+              expect(true).toBe(false);
+            } catch (error) {
+              expect(error).toBeInstanceOf(ValidationError);
+              expect(error.code).toBe('TIMESTAMP_TOO_OLD');
+              expect(error.message).toContain('7 days');
+            }
+
+            // Verify no API request was made
+            expect(mockFetch).not.toHaveBeenCalled();
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should include timestamp in request body for valid timestamps within 7 days', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.string({ minLength: 1, maxLength: 100 }).filter(s => s.trim().length > 0), // Event name
+          fc.string({ minLength: 1, maxLength: 255 }).filter(s => s.trim().length > 0), // User ID
+          validTimestamp(),
+          async (apiKey, eventName, userId, timestamp) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse());
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.events.track(eventName, userId, {}, { timestamp });
+
+            // Assert - request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+
+            // Assert - timestamp is in request body as ISO string
+            const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+            expect(callBody.timestamp).toBe(timestamp.toISOString());
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should not include timestamp in request body when not provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.string({ minLength: 1, maxLength: 100 }).filter(s => s.trim().length > 0), // Event name
+          fc.string({ minLength: 1, maxLength: 255 }).filter(s => s.trim().length > 0), // User ID
+          async (apiKey, eventName, userId) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse());
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.events.track(eventName, userId, {});
+
+            // Assert - request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+
+            // Assert - timestamp is NOT in request body
+            const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+            expect(callBody.timestamp).toBeUndefined();
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('Batch Event Tracking (trackBatch)', () => {
+    it('should throw ValidationError for any event with timestamp older than 7 days', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.integer({ min: 0, max: 9 }), // Index of the event with old timestamp
+          fc.integer({ min: 1, max: 10 }), // Total events (at least 1)
+          oldTimestamp(),
+          async (apiKey, oldTimestampIndex, totalEvents, timestamp) => {
+            // Ensure oldTimestampIndex is within bounds
+            const actualIndex = oldTimestampIndex % totalEvents;
+            
+            // Arrange
+            mockFetch.mockClear();
+            const sdk = new Rooguys(apiKey);
+            const events = Array.from({ length: totalEvents }, (_, i) => ({
+              eventName: `event_${i}`,
+              userId: `user_${i}`,
+              ...(i === actualIndex ? { timestamp } : {}),
+            }));
+
+            // Act & Assert
+            try {
+              await sdk.events.trackBatch(events);
+              // Should not reach here
+              expect(true).toBe(false);
+            } catch (error) {
+              expect(error).toBeInstanceOf(ValidationError);
+              expect(error.code).toBe('TIMESTAMP_TOO_OLD');
+              expect(error.message).toContain(`index ${actualIndex}`);
+            }
+
+            // Verify no API request was made
+            expect(mockFetch).not.toHaveBeenCalled();
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should include timestamps in batch request for valid timestamps', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.array(
+            fc.record({
+              eventName: fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0),
+              userId: fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0),
+              hasTimestamp: fc.boolean(),
+            }),
+            { minLength: 1, maxLength: 20 }
+          ),
+          async (apiKey, eventConfigs) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createBatchSuccessResponse(eventConfigs.length));
+            const sdk = new Rooguys(apiKey);
+            
+            // Create events with valid timestamps for those that should have them
+            const events = eventConfigs.map((config, i) => ({
+              eventName: config.eventName,
+              userId: config.userId,
+              ...(config.hasTimestamp ? { timestamp: new Date(Date.now() - i * 60 * 60 * 1000) } : {}), // Each event i hours ago
+            }));
+
+            // Act
+            await sdk.events.trackBatch(events);
+
+            // Assert - request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+
+            // Assert - timestamps are correctly included/excluded
+            const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+            eventConfigs.forEach((config, i) => {
+              if (config.hasTimestamp) {
+                expect(callBody.events[i].timestamp).toBeDefined();
+                expect(typeof callBody.events[i].timestamp).toBe('string');
+              } else {
+                expect(callBody.events[i].timestamp).toBeUndefined();
+              }
+            });
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should accept batch where all events have valid timestamps', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.integer({ min: 1, max: 20 }), // Number of events
+          async (apiKey, eventCount) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createBatchSuccessResponse(eventCount));
+            const sdk = new Rooguys(apiKey);
+            
+            // Create events with valid timestamps (within 7 days)
+            const events = Array.from({ length: eventCount }, (_, i) => ({
+              eventName: `event_${i}`,
+              userId: `user_${i}`,
+              timestamp: new Date(Date.now() - i * 60 * 60 * 1000), // Each event i hours ago
+            }));
+
+            // Act
+            const result = await sdk.events.trackBatch(events);
+
+            // Assert - request was made and succeeded
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            expect(result.results).toHaveLength(eventCount);
+
+            // Assert - all timestamps are in ISO format
+            const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+            callBody.events.forEach((event, i) => {
+              expect(event.timestamp).toBe(events[i].timestamp.toISOString());
+            });
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('Boundary Conditions', () => {
+    it('should accept timestamp exactly at 7 day boundary', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.integer({ min: 0, max: 1000 }), // Milliseconds before the 7-day boundary
+          async (apiKey, msBeforeBoundary) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse());
+            const sdk = new Rooguys(apiKey);
+            
+            // Timestamp just within 7 days (7 days minus some milliseconds)
+            const timestamp = new Date(Date.now() - SEVEN_DAYS_MS + msBeforeBoundary + 1000); // +1000ms buffer
+
+            // Act
+            await sdk.events.track('test_event', 'user_123', {}, { timestamp });
+
+            // Assert - request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            
+            // Assert - timestamp is in request body
+            const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+            expect(callBody.timestamp).toBe(timestamp.toISOString());
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should reject timestamp just past 7 day boundary', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.integer({ min: 1000, max: 100000 }), // Milliseconds past the 7-day boundary
+          async (apiKey, msPastBoundary) => {
+            // Arrange
+            mockFetch.mockClear();
+            const sdk = new Rooguys(apiKey);
+            
+            // Timestamp just past 7 days
+            const timestamp = new Date(Date.now() - SEVEN_DAYS_MS - msPastBoundary);
+
+            // Act & Assert
+            try {
+              await sdk.events.track('test_event', 'user_123', {}, { timestamp });
+              expect(true).toBe(false); // Should not reach here
+            } catch (error) {
+              expect(error).toBeInstanceOf(ValidationError);
+              expect(error.code).toBe('TIMESTAMP_TOO_OLD');
+            }
+
+            // Verify no API request was made
+            expect(mockFetch).not.toHaveBeenCalled();
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+});

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

@@ -1,6 +1,7 @@
 import { jest } from '@jest/globals';
-import Rooguys from '../../index.js';
+import Rooguys, { ValidationError } from '../../index.js';
 import { mockResponses, mockErrors } from '../fixtures/responses.js';
+import { createMockHeaders } from '../utils/mockClient.js';
 
 describe('Aha Resource', () => {
   let client;
@@ -19,7 +20,12 @@ describe('Aha Resource', () => {
     it('should declare aha score with valid value', async () => {
       global.fetch = jest.fn().mockResolvedValue({
         ok: true,
-        json: async () => mockResponses.ahaDeclarationResponse,
+        headers: createMockHeaders({
+          'X-RateLimit-Limit': '1000',
+          'X-RateLimit-Remaining': '950',
+          'X-RateLimit-Reset': '1704067200',
+        }),
+        json: async () => ({ success: true, data: mockResponses.ahaDeclarationResponse }),
       });
 
       const result = await client.aha.declare('user123', 4);
@@ -37,7 +43,12 @@ describe('Aha Resource', () => {
     it('should declare aha score with value 1', async () => {
       global.fetch = jest.fn().mockResolvedValue({
         ok: true,
-        json: async () => mockResponses.ahaDeclarationResponse,
+        headers: createMockHeaders({
+          'X-RateLimit-Limit': '1000',
+          'X-RateLimit-Remaining': '950',
+          'X-RateLimit-Reset': '1704067200',
+        }),
+        json: async () => ({ success: true, data: mockResponses.ahaDeclarationResponse }),
       });
 
       const result = await client.aha.declare('user123', 1);
@@ -54,7 +65,12 @@ describe('Aha Resource', () => {
     it('should declare aha score with value 5', async () => {
       global.fetch = jest.fn().mockResolvedValue({
         ok: true,
-        json: async () => mockResponses.ahaDeclarationResponse,
+        headers: createMockHeaders({
+          'X-RateLimit-Limit': '1000',
+          'X-RateLimit-Remaining': '950',
+          'X-RateLimit-Reset': '1704067200',
+        }),
+        json: async () => ({ success: true, data: mockResponses.ahaDeclarationResponse }),
       });
 
       const result = await client.aha.declare('user123', 5);
@@ -68,35 +84,29 @@ describe('Aha Resource', () => {
       expect(result).toEqual(mockResponses.ahaDeclarationResponse);
     });
 
-    it('should throw error for value 0', () => {
-      expect(() => client.aha.declare('user123', 0)).toThrow(
-        'Aha score value must be an integer between 1 and 5'
-      );
+    it('should throw ValidationError for value 0', async () => {
+      await expect(client.aha.declare('user123', 0)).rejects.toThrow(ValidationError);
     });
 
-    it('should throw error for value 6', () => {
-      expect(() => client.aha.declare('user123', 6)).toThrow(
-        'Aha score value must be an integer between 1 and 5'
-      );
+    it('should throw ValidationError for value 6', async () => {
+      await expect(client.aha.declare('user123', 6)).rejects.toThrow(ValidationError);
     });
 
-    it('should throw error for negative value', () => {
-      expect(() => client.aha.declare('user123', -1)).toThrow(
-        'Aha score value must be an integer between 1 and 5'
-      );
+    it('should throw ValidationError for negative value', async () => {
+      await expect(client.aha.declare('user123', -1)).rejects.toThrow(ValidationError);
     });
 
-    it('should throw error for non-integer value', () => {
-      expect(() => client.aha.declare('user123', 3.5)).toThrow(
-        'Aha score value must be an integer between 1 and 5'
-      );
+    it('should throw ValidationError for non-integer value', async () => {
+      await expect(client.aha.declare('user123', 3.5)).rejects.toThrow(ValidationError);
     });
 
     it('should handle API error response', async () => {
       global.fetch = jest.fn().mockResolvedValue({
         ok: false,
+        status: 400,
         statusText: 'Bad Request',
-        json: async () => mockErrors.ahaValueError,
+        headers: createMockHeaders({}),
+        json: async () => ({ success: false, error: mockErrors.ahaValueError }),
       });
 
       await expect(client.aha.declare('user123', 3)).rejects.toThrow();
@@ -107,7 +117,12 @@ describe('Aha Resource', () => {
     it('should get user aha score successfully', async () => {
       global.fetch = jest.fn().mockResolvedValue({
         ok: true,
-        json: async () => mockResponses.ahaScoreResponse,
+        headers: createMockHeaders({
+          'X-RateLimit-Limit': '1000',
+          'X-RateLimit-Remaining': '950',
+          'X-RateLimit-Reset': '1704067200',
+        }),
+        json: async () => ({ success: true, data: mockResponses.ahaScoreResponse }),
       });
 
       const result = await client.aha.getUserScore('user123');
@@ -121,7 +136,12 @@ describe('Aha Resource', () => {
     it('should parse all aha score fields correctly', async () => {
       global.fetch = jest.fn().mockResolvedValue({
         ok: true,
-        json: async () => mockResponses.ahaScoreResponse,
+        headers: createMockHeaders({
+          'X-RateLimit-Limit': '1000',
+          'X-RateLimit-Remaining': '950',
+          'X-RateLimit-Reset': '1704067200',
+        }),
+        json: async () => ({ success: true, data: mockResponses.ahaScoreResponse }),
       });
 
       const result = await client.aha.getUserScore('user123');
@@ -137,7 +157,12 @@ describe('Aha Resource', () => {
     it('should preserve history structure', async () => {
       global.fetch = jest.fn().mockResolvedValue({
         ok: true,
-        json: async () => mockResponses.ahaScoreResponse,
+        headers: createMockHeaders({
+          'X-RateLimit-Limit': '1000',
+          'X-RateLimit-Remaining': '950',
+          'X-RateLimit-Reset': '1704067200',
+        }),
+        json: async () => ({ success: true, data: mockResponses.ahaScoreResponse }),
       });
 
       const result = await client.aha.getUserScore('user123');
@@ -154,7 +179,8 @@ describe('Aha Resource', () => {
         ok: false,
         status: 404,
         statusText: 'Not Found',
-        json: async () => mockErrors.notFoundError,
+        headers: createMockHeaders({}),
+        json: async () => ({ success: false, error: mockErrors.notFoundError }),
       });
 
       await expect(client.aha.getUserScore('nonexistent')).rejects.toThrow();
@@ -178,7 +204,12 @@ describe('Aha Resource', () => {
       };
       global.fetch = jest.fn().mockResolvedValue({
         ok: true,
-        json: async () => responseWithNulls,
+        headers: createMockHeaders({
+          'X-RateLimit-Limit': '1000',
+          'X-RateLimit-Remaining': '950',
+          'X-RateLimit-Reset': '1704067200',
+        }),
+        json: async () => ({ success: true, data: responseWithNulls }),
       });
 
       const result = await client.aha.getUserScore('user123');

package/src/__tests__/unit/config.test.js

@@ -1,4 +1,5 @@
 import Rooguys from '../../index';
+import { createMockHeaders } from '../utils/mockClient';
 
 describe('SDK Configuration', () => {
   beforeEach(() => {
@@ -71,7 +72,12 @@ describe('SDK Configuration', () => {
       const client = new Rooguys('my-secret-key');
       global.fetch.mockResolvedValue({
         ok: true,
-        json: () => Promise.resolve({}),
+        headers: createMockHeaders({
+          'X-RateLimit-Limit': '1000',
+          'X-RateLimit-Remaining': '950',
+          'X-RateLimit-Reset': '1704067200',
+        }),
+        json: () => Promise.resolve({ success: true, data: {} }),
       });
 
       await client.events.track('test', 'user1');

package/src/__tests__/unit/errors.test.js

@@ -1,5 +1,5 @@
 import Rooguys from '../../index';
-import { mockErrorResponse, mockTimeoutError, mockNetworkError } from '../utils/mockClient';
+import { mockErrorResponse, mockTimeoutError, mockNetworkError, createMockHeaders } from '../utils/mockClient';
 import { mockErrors } from '../fixtures/responses';
 
 describe('Error Handling', () => {
@@ -71,7 +71,7 @@ describe('Error Handling', () => {
     it('should throw error for network timeout', async () => {
       global.fetch.mockRejectedValue(mockTimeoutError());
 
-      await expect(client.events.track('test', 'user1')).rejects.toThrow('aborted');
+      await expect(client.events.track('test', 'user1')).rejects.toThrow('Request timeout');
     });
 
     it('should throw error for network failure', async () => {
@@ -93,12 +93,11 @@ describe('Error Handling', () => {
         ok: false,
         status: 500,
         statusText: 'Internal Server Error',
+        headers: createMockHeaders({}),
         json: () => Promise.resolve({}),
       });
 
-      await expect(client.events.track('test', 'user1')).rejects.toThrow(
-        'Internal Server Error'
-      );
+      await expect(client.events.track('test', 'user1')).rejects.toThrow();
     });
 
     it('should handle response with invalid JSON', async () => {
@@ -106,12 +105,11 @@ describe('Error Handling', () => {
         ok: false,
         status: 500,
         statusText: 'Internal Server Error',
+        headers: createMockHeaders({}),
         json: () => Promise.reject(new Error('Invalid JSON')),
       });
 
-      await expect(client.events.track('test', 'user1')).rejects.toThrow(
-        'Internal Server Error'
-      );
+      await expect(client.events.track('test', 'user1')).rejects.toThrow();
     });
   });