@rooguys/js 0.1.0 → 1.0.0

package/src/__tests__/fixtures/responses.js

@@ -2,6 +2,23 @@
  * Mock API response fixtures for testing
  */
 
+// Standardized response format helpers
+export const wrapSuccess = (data, requestId = 'req_test123') => ({
+  success: true,
+  data,
+  request_id: requestId,
+});
+
+export const wrapError = (code, message, details = null, requestId = 'req_test123') => ({
+  success: false,
+  error: {
+    code,
+    message,
+    ...(details && { details }),
+  },
+  request_id: requestId,
+});
+
 export const mockResponses = {
   userProfile: {
     user_id: 'user123',
@@ -65,6 +82,21 @@ export const mockResponses = {
     },
   },
 
+  batchTrackEventResponse: {
+    results: [
+      { index: 0, status: 'queued' },
+      { index: 1, status: 'queued' },
+    ],
+  },
+
+  batchTrackEventWithErrorResponse: {
+    results: [
+      { index: 0, status: 'queued' },
+      { index: 1, status: 'error', error: 'Invalid event name' },
+      { index: 2, status: 'queued' },
+    ],
+  },
+
   leaderboardResponse: {
     timeframe: 'all-time',
     page: 1,
@@ -276,6 +308,95 @@ export const mockResponses = {
       totalPages: 1,
     },
   },
+
+  // Enhanced leaderboard responses with filters and cache metadata
+  leaderboardWithFiltersResponse: {
+    timeframe: 'all-time',
+    page: 1,
+    limit: 50,
+    total: 50,
+    rankings: [
+      {
+        rank: 1,
+        user_id: 'user1',
+        points: 1000,
+        percentile: 99.5,
+        level: {
+          id: 'level3',
+          name: 'Gold',
+          level_number: 3,
+        },
+      },
+      {
+        rank: 2,
+        user_id: 'user2',
+        points: 900,
+        percentile: 98.0,
+        level: {
+          id: 'level2',
+          name: 'Silver',
+          level_number: 2,
+        },
+      },
+    ],
+    cache_metadata: {
+      cached_at: '2024-01-15T10:30:00Z',
+      ttl: 300,
+    },
+  },
+
+  aroundUserResponse: {
+    user: {
+      user_id: 'user123',
+      rank: 42,
+      points: 850,
+      percentile: 95.8,
+    },
+    rankings: [
+      {
+        rank: 40,
+        user_id: 'user40',
+        points: 870,
+        percentile: 96.0,
+      },
+      {
+        rank: 41,
+        user_id: 'user41',
+        points: 860,
+        percentile: 95.9,
+      },
+      {
+        rank: 42,
+        user_id: 'user123',
+        points: 850,
+        percentile: 95.8,
+      },
+      {
+        rank: 43,
+        user_id: 'user43',
+        points: 840,
+        percentile: 95.7,
+      },
+      {
+        rank: 44,
+        user_id: 'user44',
+        points: 830,
+        percentile: 95.6,
+      },
+    ],
+    cache_metadata: {
+      cached_at: '2024-01-15T10:30:00Z',
+      ttl: 60,
+    },
+  },
+
+  userRankWithPercentileResponse: {
+    user_id: 'user123',
+    rank: 42,
+    points: 850,
+    total_users: 1000,
+    percentile: 95.8,
+  },
 };
 
 export const mockErrors = {
@@ -328,3 +449,131 @@ export const mockErrors = {
     ],
   },
 };
+
+
+// Standardized format responses
+export const standardizedResponses = {
+  userProfile: wrapSuccess({
+    user_id: 'user123',
+    points: 100,
+    persona: 'Achiever',
+    level: {
+      id: 'level1',
+      name: 'Bronze',
+      level_number: 1,
+      points_required: 0,
+    },
+    next_level: {
+      id: 'level2',
+      name: 'Silver',
+      level_number: 2,
+      points_required: 500,
+      points_needed: 400,
+    },
+    metrics: {
+      logins: 10,
+      purchases: 2,
+    },
+    badges: [],
+    activity_summary: {
+      last_event_at: '2024-01-15T10:30:00Z',
+      event_count: 150,
+      days_active: 30,
+    },
+  }),
+
+  trackEventResponse: wrapSuccess({
+    status: 'queued',
+    message: 'Event accepted for processing',
+  }),
+
+  batchTrackResponse: wrapSuccess({
+    results: [
+      { index: 0, status: 'queued' },
+      { index: 1, status: 'queued' },
+      { index: 2, status: 'error', error: 'Invalid event name' },
+    ],
+  }),
+
+  leaderboardResponse: wrapSuccess({
+    timeframe: 'all-time',
+    rankings: [
+      {
+        rank: 1,
+        user_id: 'user1',
+        score: 1000,
+        level_name: 'Gold',
+        level_number: 3,
+        percentile: 99.5,
+      },
+      {
+        rank: 2,
+        user_id: 'user2',
+        score: 900,
+        level_name: 'Silver',
+        level_number: 2,
+        percentile: 98.0,
+      },
+    ],
+    stats: {
+      total_users: 1000,
+      average_score: 250,
+    },
+    pagination: {
+      page: 1,
+      limit: 50,
+      total: 1000,
+      totalPages: 20,
+    },
+  }),
+
+  healthResponse: wrapSuccess({
+    status: 'healthy',
+    version: '1.0.0',
+    timestamp: '2024-01-15T10:30:00Z',
+    services: {
+      database: 'healthy',
+      redis: 'healthy',
+      queue: 'healthy',
+    },
+    queue_depth: 150,
+    processing_lag_ms: 50,
+  }),
+};
+
+export const standardizedErrors = {
+  validationError: wrapError('VALIDATION_ERROR', 'Validation failed', [
+    { field: 'user_id', message: 'User ID is required' },
+    { field: 'event_name', message: 'Event name is required' },
+  ]),
+
+  authenticationError: wrapError('INVALID_API_KEY', 'Invalid or missing API key'),
+
+  notFoundError: wrapError('USER_NOT_FOUND', "User 'user123' does not exist"),
+
+  conflictError: wrapError('USER_EXISTS', 'User with this ID already exists'),
+
+  rateLimitError: wrapError('RATE_LIMIT_EXCEEDED', 'Rate limit exceeded. Please retry later.'),
+
+  serverError: wrapError('INTERNAL_ERROR', 'An internal server error occurred'),
+};
+
+// Rate limit headers for testing
+export const rateLimitHeaders = {
+  normal: {
+    'X-RateLimit-Limit': '1000',
+    'X-RateLimit-Remaining': '950',
+    'X-RateLimit-Reset': '1704067200',
+  },
+  warning: {
+    'X-RateLimit-Limit': '1000',
+    'X-RateLimit-Remaining': '150',
+    'X-RateLimit-Reset': '1704067200',
+  },
+  exceeded: {
+    'X-RateLimit-Limit': '1000',
+    'X-RateLimit-Remaining': '0',
+    'X-RateLimit-Reset': '1704067200',
+    'Retry-After': '60',
+  },
+};

package/src/__tests__/property/batch-event-validation.property.test.js

@@ -0,0 +1,225 @@
+/**
+ * Property-Based Test: Batch Event Validation
+ * Feature: sdk-documentation-update, Property 4: Batch Event Validation
+ * Validates: Requirements 3.1, 3.2
+ * 
+ * For any array of events passed to trackBatch(), if the array length exceeds 100,
+ * the SDK SHALL throw a ValidationError before making an API request.
+ * If the array length is between 1 and 100, the SDK SHALL make exactly one API request.
+ */
+
+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 4: Batch Event Validation', () => {
+  let mockFetch;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+    global.fetch = mockFetch;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  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 valid batch events
+  const validBatchEvent = fc.record({
+    eventName: fc.string({ minLength: 1, maxLength: 100 }).filter(s => s.trim().length > 0),
+    userId: fc.string({ minLength: 1, maxLength: 255 }).filter(s => s.trim().length > 0),
+    properties: fc.option(
+      fc.dictionary(
+        fc.string({ minLength: 1, maxLength: 50 }),
+        fc.oneof(fc.string(), fc.integer(), fc.boolean(), fc.constant(null))
+      ),
+      { nil: undefined }
+    ),
+  });
+
+  it('should throw ValidationError for arrays exceeding 100 events without making API request', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }), // API key
+        fc.integer({ min: 101, max: 500 }), // Array size > 100
+        async (apiKey, arraySize) => {
+          // Arrange
+          mockFetch.mockClear();
+          const sdk = new Rooguys(apiKey);
+          const events = Array.from({ length: arraySize }, (_, i) => ({
+            eventName: `event_${i}`,
+            userId: `user_${i}`,
+          }));
+
+          // Act & Assert
+          await expect(sdk.events.trackBatch(events)).rejects.toThrow(ValidationError);
+          await expect(sdk.events.trackBatch(events)).rejects.toThrow('Batch size exceeds maximum of 100 events');
+          
+          // Verify no API request was made
+          expect(mockFetch).not.toHaveBeenCalled();
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should make exactly one API request for valid batch sizes (1-100)', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }), // API key
+        fc.integer({ min: 1, max: 100 }), // Valid array size
+        async (apiKey, arraySize) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue(createBatchSuccessResponse(arraySize));
+          const sdk = new Rooguys(apiKey);
+          const events = Array.from({ length: arraySize }, (_, i) => ({
+            eventName: `event_${i}`,
+            userId: `user_${i}`,
+          }));
+
+          // Act
+          const result = await sdk.events.trackBatch(events);
+
+          // Assert - exactly one API request
+          expect(mockFetch).toHaveBeenCalledTimes(1);
+          
+          // Verify the request was to the batch endpoint
+          const callUrl = mockFetch.mock.calls[0][0];
+          expect(callUrl).toContain('/events/batch');
+          
+          // Verify the request body contains all events
+          const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+          expect(callBody.events).toHaveLength(arraySize);
+          
+          // Verify response contains results for all events
+          expect(result.results).toHaveLength(arraySize);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should throw ValidationError for empty arrays without making API request', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }), // API key
+        async (apiKey) => {
+          // Arrange
+          mockFetch.mockClear();
+          const sdk = new Rooguys(apiKey);
+
+          // Act & Assert
+          await expect(sdk.events.trackBatch([])).rejects.toThrow(ValidationError);
+          await expect(sdk.events.trackBatch([])).rejects.toThrow('Events array cannot be empty');
+          
+          // Verify no API request was made
+          expect(mockFetch).not.toHaveBeenCalled();
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should throw ValidationError for non-array inputs without making API request', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }), // API key
+        fc.oneof(
+          fc.string(),
+          fc.integer(),
+          fc.boolean(),
+          fc.constant(null),
+          fc.constant(undefined),
+          fc.record({ eventName: fc.string(), userId: fc.string() }) // Single object instead of array
+        ),
+        async (apiKey, invalidInput) => {
+          // Arrange
+          mockFetch.mockClear();
+          const sdk = new Rooguys(apiKey);
+
+          // Act & Assert
+          await expect(sdk.events.trackBatch(invalidInput)).rejects.toThrow(ValidationError);
+          
+          // Verify no API request was made
+          expect(mockFetch).not.toHaveBeenCalled();
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should correctly transform event properties in batch request', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }), // API key
+        fc.array(validBatchEvent, { minLength: 1, maxLength: 50 }),
+        async (apiKey, events) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue(createBatchSuccessResponse(events.length));
+          const sdk = new Rooguys(apiKey);
+
+          // Act
+          await sdk.events.trackBatch(events);
+
+          // Assert - verify transformation
+          const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+          
+          events.forEach((event, index) => {
+            expect(callBody.events[index].event_name).toBe(event.eventName);
+            expect(callBody.events[index].user_id).toBe(event.userId);
+            expect(callBody.events[index].properties).toEqual(event.properties || {});
+          });
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should return individual status for each event in batch', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }), // API key
+        fc.integer({ min: 1, max: 50 }), // Batch size
+        async (apiKey, batchSize) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue(createBatchSuccessResponse(batchSize));
+          const sdk = new Rooguys(apiKey);
+          const events = Array.from({ length: batchSize }, (_, i) => ({
+            eventName: `event_${i}`,
+            userId: `user_${i}`,
+          }));
+
+          // Act
+          const result = await sdk.events.trackBatch(events);
+
+          // Assert - each event has a status
+          expect(result.results).toHaveLength(batchSize);
+          result.results.forEach((eventResult, index) => {
+            expect(eventResult.index).toBe(index);
+            expect(eventResult.status).toBeDefined();
+          });
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+});