@rooguys/js 0.1.0 → 1.0.0

package/src/__tests__/property/field-selection.property.test.js

@@ -0,0 +1,297 @@
+/**
+ * Property-Based Test: Field Selection Query Construction
+ * Feature: sdk-documentation-update, Property 9: Field Selection Query Construction
+ * Validates: Requirements 5.1
+ * 
+ * For any user profile request with a `fields` parameter, the SDK SHALL include
+ * a `fields` query parameter with the comma-separated list of requested fields.
+ */
+
+import fc from 'fast-check';
+import { jest } from '@jest/globals';
+import Rooguys from '../../index.js';
+import { createMockFetch, createMockHeaders } from '../utils/mockClient.js';
+
+describe('Property 9: Field Selection Query 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 field names
+  const validFieldName = fc.constantFrom(
+    'user_id',
+    'display_name',
+    'email',
+    'points',
+    'level',
+    'badges',
+    'metrics',
+    'persona',
+    'activity_summary',
+    'streak',
+    'inventory',
+    'created_at',
+    'updated_at'
+  );
+
+  // Generator for array of unique field names
+  const fieldArray = fc.uniqueArray(validFieldName, { minLength: 1, maxLength: 10 });
+
+  describe('users.get()', () => {
+    it('should include fields query parameter with comma-separated values', 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
+          fieldArray,
+          async (apiKey, userId, fields) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse({
+              user_id: userId,
+            }));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.users.get(userId, { fields });
+
+            // Assert
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            // Verify fields parameter exists
+            expect(url.searchParams.has('fields')).toBe(true);
+            
+            // Verify comma-separated format
+            const fieldsParam = url.searchParams.get('fields');
+            const parsedFields = fieldsParam.split(',');
+            
+            // All requested fields should be in the query
+            expect(parsedFields.sort()).toEqual(fields.sort());
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should not include fields parameter when fields array is empty', 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
+          async (apiKey, userId) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse({
+              user_id: userId,
+            }));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.users.get(userId, { fields: [] });
+
+            // Assert
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            // Verify fields parameter is NOT present
+            expect(url.searchParams.has('fields')).toBe(false);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should not include fields parameter when options.fields is undefined', 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
+          async (apiKey, userId) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse({
+              user_id: userId,
+            }));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.users.get(userId);
+
+            // Assert
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            // Verify fields parameter is NOT present
+            expect(url.searchParams.has('fields')).toBe(false);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should preserve field order in comma-separated list', 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
+          fieldArray,
+          async (apiKey, userId, fields) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse({
+              user_id: userId,
+            }));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.users.get(userId, { fields });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            const fieldsParam = url.searchParams.get('fields');
+            const parsedFields = fieldsParam.split(',');
+            
+            // Fields should be in the same order as provided
+            expect(parsedFields).toEqual(fields);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('users.search()', () => {
+    it('should include fields query parameter in search requests', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.string({ minLength: 1, maxLength: 50 }), // Search query
+          fieldArray,
+          async (apiKey, query, fields) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse({
+              users: [],
+              pagination: { page: 1, limit: 50, total: 0, totalPages: 0 },
+            }));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.users.search(query, { fields });
+
+            // Assert
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            // Verify fields parameter exists
+            expect(url.searchParams.has('fields')).toBe(true);
+            
+            // Verify comma-separated format
+            const fieldsParam = url.searchParams.get('fields');
+            const parsedFields = fieldsParam.split(',');
+            
+            // All requested fields should be in the query
+            expect(parsedFields.sort()).toEqual(fields.sort());
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should include both search query and fields parameters', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.string({ minLength: 1, maxLength: 50 }), // Search query
+          fieldArray,
+          fc.integer({ min: 1, max: 10 }), // Page
+          fc.integer({ min: 1, max: 100 }), // Limit
+          async (apiKey, query, fields, page, limit) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse({
+              users: [],
+              pagination: { page, limit, total: 0, totalPages: 0 },
+            }));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.users.search(query, { fields, page, limit });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            // Verify all parameters are present
+            expect(url.searchParams.get('q')).toBe(query);
+            expect(url.searchParams.get('page')).toBe(String(page));
+            expect(url.searchParams.get('limit')).toBe(String(limit));
+            expect(url.searchParams.has('fields')).toBe(true);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('field selection with special characters', () => {
+    it('should properly URL-encode field names with special characters', 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
+          async (apiKey, userId) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse({
+              user_id: userId,
+            }));
+            const sdk = new Rooguys(apiKey);
+            const fields = ['user_id', 'display_name', 'activity_summary'];
+
+            // Act
+            await sdk.users.get(userId, { fields });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            
+            // The URL should be properly encoded
+            expect(callUrl).toContain('fields=');
+            
+            // Decode and verify
+            const url = new URL(callUrl);
+            const fieldsParam = url.searchParams.get('fields');
+            expect(fieldsParam).toBe('user_id,display_name,activity_summary');
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+});

package/src/__tests__/property/idempotency-key.property.test.js

@@ -0,0 +1,350 @@
+/**
+ * Property-Based Test: Idempotency Key Propagation
+ * Feature: sdk-documentation-update, Property 6: Idempotency Key Propagation
+ * Validates: Requirements 3.3, 3.4
+ * 
+ * For any request with an idempotency key provided, the SDK SHALL include the
+ * X-Idempotency-Key header with the exact value provided. For requests without
+ * an idempotency key, the header SHALL NOT be present.
+ */
+
+import fc from 'fast-check';
+import { jest } from '@jest/globals';
+import Rooguys from '../../index.js';
+import { createMockFetch, createMockHeaders } from '../utils/mockClient.js';
+
+describe('Property 6: Idempotency Key Propagation', () => {
+  let mockFetch;
+
+  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 idempotency keys - various formats that might be used
+  const idempotencyKey = () => fc.oneof(
+    fc.uuid(), // UUID format
+    fc.string({ minLength: 1, maxLength: 100 }).filter(s => s.trim().length > 0), // Arbitrary string
+    fc.hexaString({ minLength: 16, maxLength: 64 }), // Hex string
+    fc.string({ minLength: 10, maxLength: 50 }).map(s => `idem_${s}`), // Prefixed format
+  );
+
+  describe('Single Event Tracking (track)', () => {
+    it('should include X-Idempotency-Key header with exact value when 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
+          idempotencyKey(),
+          async (apiKey, eventName, userId, idempotencyKeyValue) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse());
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.events.track(eventName, userId, {}, { idempotencyKey: idempotencyKeyValue });
+
+            // Assert - request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+
+            // Assert - X-Idempotency-Key header is present with exact value
+            const callHeaders = mockFetch.mock.calls[0][1].headers;
+            expect(callHeaders['X-Idempotency-Key']).toBe(idempotencyKeyValue);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should NOT include X-Idempotency-Key header 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 - X-Idempotency-Key header is NOT present
+            const callHeaders = mockFetch.mock.calls[0][1].headers;
+            expect(callHeaders['X-Idempotency-Key']).toBeUndefined();
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should NOT include X-Idempotency-Key header when options object is empty', 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 - explicitly pass empty options
+            await sdk.events.track(eventName, userId, {}, {});
+
+            // Assert - request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+
+            // Assert - X-Idempotency-Key header is NOT present
+            const callHeaders = mockFetch.mock.calls[0][1].headers;
+            expect(callHeaders['X-Idempotency-Key']).toBeUndefined();
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('Batch Event Tracking (trackBatch)', () => {
+    it('should include X-Idempotency-Key header with exact value when provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.integer({ min: 1, max: 50 }), // Number of events
+          idempotencyKey(),
+          async (apiKey, eventCount, idempotencyKeyValue) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createBatchSuccessResponse(eventCount));
+            const sdk = new Rooguys(apiKey);
+            const events = Array.from({ length: eventCount }, (_, i) => ({
+              eventName: `event_${i}`,
+              userId: `user_${i}`,
+            }));
+
+            // Act
+            await sdk.events.trackBatch(events, { idempotencyKey: idempotencyKeyValue });
+
+            // Assert - request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+
+            // Assert - X-Idempotency-Key header is present with exact value
+            const callHeaders = mockFetch.mock.calls[0][1].headers;
+            expect(callHeaders['X-Idempotency-Key']).toBe(idempotencyKeyValue);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should NOT include X-Idempotency-Key header when not provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.integer({ min: 1, max: 50 }), // Number of events
+          async (apiKey, eventCount) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createBatchSuccessResponse(eventCount));
+            const sdk = new Rooguys(apiKey);
+            const events = Array.from({ length: eventCount }, (_, i) => ({
+              eventName: `event_${i}`,
+              userId: `user_${i}`,
+            }));
+
+            // Act
+            await sdk.events.trackBatch(events);
+
+            // Assert - request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+
+            // Assert - X-Idempotency-Key header is NOT present
+            const callHeaders = mockFetch.mock.calls[0][1].headers;
+            expect(callHeaders['X-Idempotency-Key']).toBeUndefined();
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should NOT include X-Idempotency-Key header when options object is empty', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.integer({ min: 1, max: 50 }), // Number of events
+          async (apiKey, eventCount) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createBatchSuccessResponse(eventCount));
+            const sdk = new Rooguys(apiKey);
+            const events = Array.from({ length: eventCount }, (_, i) => ({
+              eventName: `event_${i}`,
+              userId: `user_${i}`,
+            }));
+
+            // Act - explicitly pass empty options
+            await sdk.events.trackBatch(events, {});
+
+            // Assert - request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+
+            // Assert - X-Idempotency-Key header is NOT present
+            const callHeaders = mockFetch.mock.calls[0][1].headers;
+            expect(callHeaders['X-Idempotency-Key']).toBeUndefined();
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('Idempotency Key Value Preservation', () => {
+    it('should preserve special characters in idempotency key', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          // Generate keys with special characters
+          fc.string({ minLength: 1, maxLength: 50 }).map(s => `key-${s}-!@#$%^&*()`),
+          async (apiKey, idempotencyKeyValue) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse());
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.events.track('test_event', 'user_123', {}, { idempotencyKey: idempotencyKeyValue });
+
+            // Assert - exact value is preserved
+            const callHeaders = mockFetch.mock.calls[0][1].headers;
+            expect(callHeaders['X-Idempotency-Key']).toBe(idempotencyKeyValue);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should preserve unicode characters in idempotency key', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          // Generate keys with unicode characters
+          fc.unicodeString({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0),
+          async (apiKey, idempotencyKeyValue) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse());
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.events.track('test_event', 'user_123', {}, { idempotencyKey: idempotencyKeyValue });
+
+            // Assert - exact value is preserved
+            const callHeaders = mockFetch.mock.calls[0][1].headers;
+            expect(callHeaders['X-Idempotency-Key']).toBe(idempotencyKeyValue);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should preserve whitespace in idempotency key', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          // Generate keys with whitespace
+          fc.tuple(
+            fc.string({ minLength: 1, maxLength: 20 }),
+            fc.constantFrom(' ', '  ', '\t'),
+            fc.string({ minLength: 1, maxLength: 20 })
+          ).map(([a, ws, b]) => `${a}${ws}${b}`),
+          async (apiKey, idempotencyKeyValue) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse());
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.events.track('test_event', 'user_123', {}, { idempotencyKey: idempotencyKeyValue });
+
+            // Assert - exact value is preserved including whitespace
+            const callHeaders = mockFetch.mock.calls[0][1].headers;
+            expect(callHeaders['X-Idempotency-Key']).toBe(idempotencyKeyValue);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('Consistency Across Methods', () => {
+    it('should handle idempotency key consistently between track and trackBatch', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          idempotencyKey(),
+          async (apiKey, idempotencyKeyValue) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse());
+            const sdk = new Rooguys(apiKey);
+
+            // Act - track single event
+            await sdk.events.track('test_event', 'user_123', {}, { idempotencyKey: idempotencyKeyValue });
+            const trackHeaders = mockFetch.mock.calls[0][1].headers;
+
+            // Reset and test batch
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createBatchSuccessResponse(1));
+            await sdk.events.trackBatch([{ eventName: 'test_event', userId: 'user_123' }], { idempotencyKey: idempotencyKeyValue });
+            const batchHeaders = mockFetch.mock.calls[0][1].headers;
+
+            // Assert - both methods handle idempotency key the same way
+            expect(trackHeaders['X-Idempotency-Key']).toBe(idempotencyKeyValue);
+            expect(batchHeaders['X-Idempotency-Key']).toBe(idempotencyKeyValue);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+});