@rooguys/js 0.1.0 → 1.0.0

package/src/__tests__/property/partial-update.property.test.js

@@ -0,0 +1,251 @@
+/**
+ * Property-Based Test: Partial Update Construction
+ * Feature: sdk-documentation-update, Property 8: Partial Update Construction
+ * Validates: Requirements 4.6
+ * 
+ * For any user update call with a subset of fields, the request body SHALL contain
+ * only the provided fields. Undefined or null fields SHALL NOT be included in the
+ * request body.
+ */
+
+import fc from 'fast-check';
+import { jest } from '@jest/globals';
+import Rooguys from '../../index.js';
+import { createMockFetch, createMockHeaders } from '../utils/mockClient.js';
+
+describe('Property 8: Partial Update Construction', () => {
+  let mockFetch;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+    global.fetch = mockFetch;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const createSuccessResponse = (data) => ({
+    ok: true,
+    headers: createMockHeaders({
+      'X-RateLimit-Limit': '1000',
+      'X-RateLimit-Remaining': '950',
+      'X-RateLimit-Reset': '1704067200',
+    }),
+    json: async () => ({
+      success: true,
+      data,
+    }),
+  });
+
+  // Generator for valid email
+  const validEmail = fc.tuple(
+    fc.string({ minLength: 1, maxLength: 20 }).filter(s => /^[a-zA-Z0-9._+-]+$/.test(s) && s.length > 0),
+    fc.string({ minLength: 1, maxLength: 15 }).filter(s => /^[a-zA-Z0-9.-]+$/.test(s) && s.length > 0),
+    fc.constantFrom('com', 'org', 'net', 'io')
+  ).map(([local, domain, tld]) => `${local}@${domain}.${tld}`);
+
+  // Generator for optional user fields
+  const optionalUserFields = fc.record({
+    displayName: fc.option(fc.string({ minLength: 1, maxLength: 100 }), { nil: undefined }),
+    email: fc.option(validEmail, { nil: undefined }),
+    firstName: fc.option(fc.string({ minLength: 1, maxLength: 50 }), { nil: undefined }),
+    lastName: fc.option(fc.string({ minLength: 1, maxLength: 50 }), { nil: undefined }),
+    metadata: fc.option(
+      fc.dictionary(
+        fc.string({ minLength: 1, maxLength: 20 }),
+        fc.oneof(fc.string(), fc.integer(), fc.boolean())
+      ),
+      { nil: undefined }
+    ),
+  });
+
+  it('should only include provided fields in request body (undefined fields excluded)', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }), // API key
+        fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0), // User ID
+        optionalUserFields,
+        async (apiKey, userId, userData) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue(createSuccessResponse({
+            user_id: userId,
+            ...userData,
+          }));
+          const sdk = new Rooguys(apiKey);
+
+          // Filter out undefined values to get expected fields
+          const providedFields = Object.entries(userData)
+            .filter(([_, value]) => value !== undefined)
+            .map(([key]) => key);
+
+          // Skip if no fields provided (nothing to update)
+          if (providedFields.length === 0) {
+            return true;
+          }
+
+          // Act
+          await sdk.users.update(userId, userData);
+
+          // Assert - parse the request body
+          expect(mockFetch).toHaveBeenCalledTimes(1);
+          const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+
+          // Map SDK field names to API field names
+          const fieldMapping = {
+            displayName: 'display_name',
+            email: 'email',
+            firstName: 'first_name',
+            lastName: 'last_name',
+            metadata: 'metadata',
+          };
+
+          // Verify only provided fields are in request body
+          const expectedApiFields = providedFields.map(f => fieldMapping[f]);
+          const actualFields = Object.keys(callBody);
+
+          // All actual fields should be expected
+          actualFields.forEach(field => {
+            expect(expectedApiFields).toContain(field);
+          });
+
+          // All expected fields should be actual
+          expectedApiFields.forEach(field => {
+            expect(actualFields).toContain(field);
+          });
+
+          // Verify undefined fields are NOT in request body
+          Object.entries(userData).forEach(([key, value]) => {
+            const apiField = fieldMapping[key];
+            if (value === undefined) {
+              expect(callBody[apiField]).toBeUndefined();
+            } else {
+              expect(callBody[apiField]).toEqual(value);
+            }
+          });
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should correctly transform field names from camelCase to snake_case', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }), // API key
+        fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0), // User ID
+        fc.string({ minLength: 1, maxLength: 100 }), // Display name
+        async (apiKey, userId, displayName) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue(createSuccessResponse({
+            user_id: userId,
+            display_name: displayName,
+          }));
+          const sdk = new Rooguys(apiKey);
+
+          // Act
+          await sdk.users.update(userId, { displayName });
+
+          // Assert
+          const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+          expect(callBody.display_name).toBe(displayName);
+          expect(callBody.displayName).toBeUndefined(); // camelCase should not be present
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should handle single field updates correctly', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }), // API key
+        fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0), // User ID
+        fc.constantFrom('displayName', 'firstName', 'lastName'),
+        fc.string({ minLength: 1, maxLength: 100 }),
+        async (apiKey, userId, fieldName, fieldValue) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue(createSuccessResponse({
+            user_id: userId,
+          }));
+          const sdk = new Rooguys(apiKey);
+
+          // Act
+          await sdk.users.update(userId, { [fieldName]: fieldValue });
+
+          // Assert - only one field in body
+          const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+          const bodyKeys = Object.keys(callBody);
+          expect(bodyKeys).toHaveLength(1);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should handle metadata updates with nested objects', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }), // API key
+        fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0), // User ID
+        fc.dictionary(
+          fc.string({ minLength: 1, maxLength: 20 }),
+          fc.oneof(
+            fc.string(),
+            fc.integer(),
+            fc.boolean(),
+            fc.constant(null)
+          )
+        ),
+        async (apiKey, userId, metadata) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue(createSuccessResponse({
+            user_id: userId,
+            metadata,
+          }));
+          const sdk = new Rooguys(apiKey);
+
+          // Act
+          await sdk.users.update(userId, { metadata });
+
+          // Assert
+          const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+          expect(callBody.metadata).toEqual(metadata);
+          expect(Object.keys(callBody)).toHaveLength(1);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should preserve exact values without modification', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }), // API key
+        fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0), // User ID
+        fc.string({ minLength: 1, maxLength: 100 }), // Display name with special chars
+        async (apiKey, userId, displayName) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue(createSuccessResponse({
+            user_id: userId,
+            display_name: displayName,
+          }));
+          const sdk = new Rooguys(apiKey);
+
+          // Act
+          await sdk.users.update(userId, { displayName });
+
+          // Assert - value should be exactly preserved
+          const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+          expect(callBody.display_name).toBe(displayName);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+});

package/src/__tests__/property/rate-limit-error.property.test.js

@@ -0,0 +1,276 @@
+/**
+ * Property-Based Test: Rate Limit Error Handling
+ * Feature: sdk-documentation-update, Property 12: Rate Limit Error Handling
+ * Validates: Requirements 7.2
+ * 
+ * For any API response with HTTP status 429, the SDK SHALL throw a RateLimitError
+ * with `retryAfter` property set to the value from the `Retry-After` header
+ * (or calculated from `X-RateLimit-Reset`).
+ */
+
+import fc from 'fast-check';
+import { jest } from '@jest/globals';
+import Rooguys from '../../index.js';
+import { RateLimitError } from '../../errors.js';
+import { createMockFetch, createMockHeaders } from '../utils/mockClient.js';
+
+describe('Property 12: Rate Limit Error Handling', () => {
+  let mockFetch;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+    global.fetch = mockFetch;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const createRateLimitResponse = (retryAfter, headers = {}) => ({
+    ok: false,
+    status: 429,
+    headers: createMockHeaders({
+      'Retry-After': String(retryAfter),
+      'X-RateLimit-Limit': '1000',
+      'X-RateLimit-Remaining': '0',
+      'X-RateLimit-Reset': String(Math.floor(Date.now() / 1000) + retryAfter),
+      'X-Request-Id': 'req_ratelimit123',
+      ...headers,
+    }),
+    json: async () => ({
+      success: false,
+      error: {
+        code: 'RATE_LIMIT_EXCEEDED',
+        message: 'Rate limit exceeded. Please retry later.',
+      },
+      request_id: 'req_ratelimit123',
+    }),
+  });
+
+  it('should throw RateLimitError with correct retryAfter from Retry-After header', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }),
+        fc.integer({ min: 1, max: 3600 }), // retryAfter in seconds (1 second to 1 hour)
+        async (apiKey, retryAfter) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue(createRateLimitResponse(retryAfter));
+          const sdk = new Rooguys(apiKey);
+
+          // Act & Assert
+          try {
+            await sdk.users.get('test-user');
+            // Should not reach here
+            expect(true).toBe(false);
+          } catch (error) {
+            // Assert - Should be RateLimitError with correct retryAfter
+            expect(error).toBeInstanceOf(RateLimitError);
+            expect(error.name).toBe('RateLimitError');
+            expect(error.statusCode).toBe(429);
+            expect(error.retryAfter).toBe(retryAfter);
+            expect(typeof error.retryAfter).toBe('number');
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should include requestId in RateLimitError', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }),
+        fc.integer({ min: 1, max: 3600 }),
+        fc.string({ minLength: 5, maxLength: 50 }).map(s => `req_${s}`),
+        async (apiKey, retryAfter, requestId) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue({
+            ok: false,
+            status: 429,
+            headers: createMockHeaders({
+              'Retry-After': String(retryAfter),
+              'X-Request-Id': requestId,
+              'X-RateLimit-Limit': '1000',
+              'X-RateLimit-Remaining': '0',
+            }),
+            json: async () => ({
+              success: false,
+              error: {
+                code: 'RATE_LIMIT_EXCEEDED',
+                message: 'Rate limit exceeded',
+              },
+              request_id: requestId,
+            }),
+          });
+          const sdk = new Rooguys(apiKey);
+
+          // Act & Assert
+          try {
+            await sdk.events.track('test-event', 'user123');
+            expect(true).toBe(false);
+          } catch (error) {
+            expect(error).toBeInstanceOf(RateLimitError);
+            expect(error.requestId).toBe(requestId);
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should use default retryAfter when Retry-After header is missing', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }),
+        async (apiKey) => {
+          // Arrange - Response without Retry-After header
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue({
+            ok: false,
+            status: 429,
+            headers: createMockHeaders({
+              'X-RateLimit-Limit': '1000',
+              'X-RateLimit-Remaining': '0',
+            }),
+            json: async () => ({
+              success: false,
+              error: {
+                code: 'RATE_LIMIT_EXCEEDED',
+                message: 'Rate limit exceeded',
+              },
+            }),
+          });
+          const sdk = new Rooguys(apiKey);
+
+          // Act & Assert
+          try {
+            await sdk.leaderboards.getGlobal();
+            expect(true).toBe(false);
+          } catch (error) {
+            expect(error).toBeInstanceOf(RateLimitError);
+            // Default retryAfter should be 60 seconds
+            expect(error.retryAfter).toBe(60);
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should include error code in RateLimitError', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }),
+        fc.integer({ min: 1, max: 3600 }),
+        fc.constantFrom('RATE_LIMIT_EXCEEDED', 'TOO_MANY_REQUESTS', 'QUOTA_EXCEEDED'),
+        async (apiKey, retryAfter, errorCode) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue({
+            ok: false,
+            status: 429,
+            headers: createMockHeaders({
+              'Retry-After': String(retryAfter),
+              'X-RateLimit-Limit': '1000',
+              'X-RateLimit-Remaining': '0',
+            }),
+            json: async () => ({
+              success: false,
+              error: {
+                code: errorCode,
+                message: 'Rate limit exceeded',
+              },
+            }),
+          });
+          const sdk = new Rooguys(apiKey);
+
+          // Act & Assert
+          try {
+            await sdk.badges.list();
+            expect(true).toBe(false);
+          } catch (error) {
+            expect(error).toBeInstanceOf(RateLimitError);
+            expect(error.code).toBe(errorCode);
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should serialize RateLimitError to JSON with retryAfter', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }),
+        fc.integer({ min: 1, max: 3600 }),
+        async (apiKey, retryAfter) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue(createRateLimitResponse(retryAfter));
+          const sdk = new Rooguys(apiKey);
+
+          // Act & Assert
+          try {
+            await sdk.levels.list();
+            expect(true).toBe(false);
+          } catch (error) {
+            expect(error).toBeInstanceOf(RateLimitError);
+            
+            // Test JSON serialization
+            const json = error.toJSON();
+            expect(json.name).toBe('RateLimitError');
+            expect(json.statusCode).toBe(429);
+            expect(json.retryAfter).toBe(retryAfter);
+            expect(typeof json.retryAfter).toBe('number');
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should throw RateLimitError for all SDK methods on 429', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 10, maxLength: 100 }),
+        fc.integer({ min: 1, max: 3600 }),
+        fc.constantFrom('users.get', 'events.track', 'leaderboards.getGlobal', 'badges.list', 'levels.list'),
+        async (apiKey, retryAfter, methodName) => {
+          // Arrange
+          mockFetch.mockClear();
+          mockFetch.mockResolvedValue(createRateLimitResponse(retryAfter));
+          const sdk = new Rooguys(apiKey);
+
+          // Act & Assert
+          try {
+            switch (methodName) {
+              case 'users.get':
+                await sdk.users.get('test-user');
+                break;
+              case 'events.track':
+                await sdk.events.track('test-event', 'user123');
+                break;
+              case 'leaderboards.getGlobal':
+                await sdk.leaderboards.getGlobal();
+                break;
+              case 'badges.list':
+                await sdk.badges.list();
+                break;
+              case 'levels.list':
+                await sdk.levels.list();
+                break;
+            }
+            expect(true).toBe(false);
+          } catch (error) {
+            expect(error).toBeInstanceOf(RateLimitError);
+            expect(error.statusCode).toBe(429);
+            expect(error.retryAfter).toBe(retryAfter);
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+});