@rooguys/sdk 0.1.0

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

@@ -0,0 +1,138 @@
+import axios from 'axios';
+import { Rooguys } from '../../index';
+import { createMockAxiosInstance, mockSuccessResponse, mockErrorResponse } from '../utils/mockClient';
+import { mockResponses, mockErrors } from '../fixtures/responses';
+
+jest.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+describe('Levels Resource', () => {
+  let client: Rooguys;
+  let mockAxiosInstance: ReturnType<typeof createMockAxiosInstance>;
+  const apiKey = 'test-api-key';
+
+  beforeEach(() => {
+    mockAxiosInstance = createMockAxiosInstance();
+    mockedAxios.create.mockReturnValue(mockAxiosInstance as any);
+    client = new Rooguys(apiKey);
+    jest.clearAllMocks();
+  });
+
+  describe('list', () => {
+    it('should list levels with default parameters', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.levelsListResponse)
+      );
+
+      const result = await client.levels.list();
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/levels', {
+        params: { page: 1, limit: 50 },
+      });
+      expect(result).toEqual(mockResponses.levelsListResponse);
+      expect(result.levels).toHaveLength(2);
+    });
+
+    it('should list levels with custom pagination', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.levelsListResponse)
+      );
+
+      await client.levels.list(2, 25);
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/levels', {
+        params: { page: 2, limit: 25 },
+      });
+    });
+
+    it('should handle empty levels list', async () => {
+      const emptyResponse = {
+        levels: [],
+        pagination: {
+          page: 1,
+          limit: 50,
+          total: 0,
+          totalPages: 0,
+        },
+      };
+      mockAxiosInstance.get.mockResolvedValue(mockSuccessResponse(emptyResponse));
+
+      const result = await client.levels.list();
+
+      expect(result.levels).toEqual([]);
+      expect(result.pagination.total).toBe(0);
+    });
+
+    it('should handle levels with all fields', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.levelsListResponse)
+      );
+
+      const result = await client.levels.list();
+
+      const level = result.levels[0];
+      expect(level.id).toBeDefined();
+      expect(level.name).toBeDefined();
+      expect(level.level_number).toBeDefined();
+      expect(level.points_required).toBeDefined();
+      expect(level.description).toBeDefined();
+      expect(level.icon_url).toBeDefined();
+    });
+
+    it('should handle levels sorted by level_number', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.levelsListResponse)
+      );
+
+      const result = await client.levels.list();
+
+      expect(result.levels[0].level_number).toBe(1);
+      expect(result.levels[1].level_number).toBe(2);
+    });
+
+    it('should throw error for invalid pagination', async () => {
+      mockAxiosInstance.get.mockRejectedValue(
+        mockErrorResponse(400, mockErrors.invalidPaginationError.message)
+      );
+
+      await expect(client.levels.list(1, 150)).rejects.toThrow(
+        'Limit must be between 1 and 100'
+      );
+    });
+
+    it('should handle server error', async () => {
+      mockAxiosInstance.get.mockRejectedValue(
+        mockErrorResponse(500, 'Internal server error')
+      );
+
+      await expect(client.levels.list()).rejects.toThrow('Internal server error');
+    });
+
+    it('should handle levels with nullable fields', async () => {
+      const levelsWithNulls = {
+        levels: [
+          {
+            id: 'level1',
+            name: 'Bronze',
+            level_number: 1,
+            points_required: 0,
+            description: null,
+            icon_url: null,
+          },
+        ],
+        pagination: {
+          page: 1,
+          limit: 50,
+          total: 1,
+          totalPages: 1,
+        },
+      };
+      mockAxiosInstance.get.mockResolvedValue(mockSuccessResponse(levelsWithNulls));
+
+      const result = await client.levels.list();
+
+      expect(result.levels[0].description).toBeNull();
+      expect(result.levels[0].icon_url).toBeNull();
+    });
+  });
+});

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

@@ -0,0 +1,138 @@
+import axios from 'axios';
+import { Rooguys } from '../../index';
+import { createMockAxiosInstance, mockSuccessResponse, mockErrorResponse } from '../utils/mockClient';
+import { mockResponses, mockErrors } from '../fixtures/responses';
+
+jest.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+describe('Questionnaires Resource', () => {
+  let client: Rooguys;
+  let mockAxiosInstance: ReturnType<typeof createMockAxiosInstance>;
+  const apiKey = 'test-api-key';
+
+  beforeEach(() => {
+    mockAxiosInstance = createMockAxiosInstance();
+    mockedAxios.create.mockReturnValue(mockAxiosInstance as any);
+    client = new Rooguys(apiKey);
+    jest.clearAllMocks();
+  });
+
+  describe('get', () => {
+    it('should get questionnaire by slug', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.questionnaireResponse)
+      );
+
+      const result = await client.questionnaires.get('user-persona');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/questionnaire/user-persona');
+      expect(result).toEqual(mockResponses.questionnaireResponse);
+      expect(result.slug).toBe('user-persona');
+    });
+
+    it('should handle questionnaire with multiple questions', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.questionnaireResponse)
+      );
+
+      const result = await client.questionnaires.get('user-persona');
+
+      expect(result.questions).toBeDefined();
+      expect(result.questions.length).toBeGreaterThan(0);
+    });
+
+    it('should handle questionnaire with answer options', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.questionnaireResponse)
+      );
+
+      const result = await client.questionnaires.get('user-persona');
+
+      const question = result.questions[0];
+      expect(question.answer_options).toBeDefined();
+      expect(question.answer_options.length).toBeGreaterThan(0);
+    });
+
+    it('should throw 404 error when questionnaire not found', async () => {
+      mockAxiosInstance.get.mockRejectedValue(
+        mockErrorResponse(404, 'Questionnaire not found')
+      );
+
+      await expect(
+        client.questionnaires.get('nonexistent-slug')
+      ).rejects.toThrow('Questionnaire not found');
+    });
+
+    it('should handle slug with special characters', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.questionnaireResponse)
+      );
+
+      await client.questionnaires.get('user-persona-v2');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/questionnaire/user-persona-v2');
+    });
+
+    it('should handle inactive questionnaire', async () => {
+      const inactiveQuestionnaire = {
+        ...mockResponses.questionnaireResponse,
+        is_active: false,
+      };
+      mockAxiosInstance.get.mockResolvedValue(mockSuccessResponse(inactiveQuestionnaire));
+
+      const result = await client.questionnaires.get('old-questionnaire');
+
+      expect(result.is_active).toBe(false);
+    });
+  });
+
+  describe('getActive', () => {
+    it('should get active questionnaire', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.questionnaireResponse)
+      );
+
+      const result = await client.questionnaires.getActive();
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/questionnaire/active');
+      expect(result).toEqual(mockResponses.questionnaireResponse);
+      expect(result.is_active).toBe(true);
+    });
+
+    it('should throw 404 error when no active questionnaire', async () => {
+      mockAxiosInstance.get.mockRejectedValue(
+        mockErrorResponse(404, 'No active questionnaire found for this project')
+      );
+
+      await expect(client.questionnaires.getActive()).rejects.toThrow(
+        'No active questionnaire found'
+      );
+    });
+
+    it('should handle active questionnaire with all fields', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.questionnaireResponse)
+      );
+
+      const result = await client.questionnaires.getActive();
+
+      expect(result.id).toBeDefined();
+      expect(result.slug).toBeDefined();
+      expect(result.title).toBeDefined();
+      expect(result.description).toBeDefined();
+      expect(result.is_active).toBe(true);
+      expect(result.questions).toBeDefined();
+    });
+
+    it('should handle server error', async () => {
+      mockAxiosInstance.get.mockRejectedValue(
+        mockErrorResponse(500, 'Internal server error')
+      );
+
+      await expect(client.questionnaires.getActive()).rejects.toThrow(
+        'Internal server error'
+      );
+    });
+  });
+});

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

@@ -0,0 +1,273 @@
+import axios from 'axios';
+import { Rooguys } from '../../index';
+import { createMockAxiosInstance, mockSuccessResponse, mockErrorResponse } from '../utils/mockClient';
+import { mockResponses, mockErrors } from '../fixtures/responses';
+
+jest.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+describe('Users Resource', () => {
+  let client: Rooguys;
+  let mockAxiosInstance: ReturnType<typeof createMockAxiosInstance>;
+  const apiKey = 'test-api-key';
+
+  beforeEach(() => {
+    mockAxiosInstance = createMockAxiosInstance();
+    mockedAxios.create.mockReturnValue(mockAxiosInstance as any);
+    client = new Rooguys(apiKey);
+    jest.clearAllMocks();
+  });
+
+  describe('get', () => {
+    it('should get a user profile', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.userProfile)
+      );
+
+      const result = await client.users.get('user_123');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/user/user_123');
+      expect(result).toEqual(mockResponses.userProfile);
+      expect(result.user_id).toBe('user123');
+      expect(result.points).toBe(100);
+    });
+
+    it('should handle user with no level', async () => {
+      const userWithoutLevel = {
+        ...mockResponses.userProfile,
+        level: null,
+        next_level: null,
+      };
+      mockAxiosInstance.get.mockResolvedValue(mockSuccessResponse(userWithoutLevel));
+
+      const result = await client.users.get('user_new');
+
+      expect(result.level).toBeNull();
+      expect(result.next_level).toBeNull();
+    });
+
+    it('should handle user with no badges', async () => {
+      const userWithoutBadges = {
+        ...mockResponses.userProfile,
+        badges: [],
+      };
+      mockAxiosInstance.get.mockResolvedValue(mockSuccessResponse(userWithoutBadges));
+
+      const result = await client.users.get('user_123');
+
+      expect(result.badges).toEqual([]);
+    });
+
+    it('should throw 404 error when user not found', async () => {
+      mockAxiosInstance.get.mockRejectedValue(
+        mockErrorResponse(404, mockErrors.notFoundError.message)
+      );
+
+      await expect(client.users.get('nonexistent_user')).rejects.toThrow(
+        "User 'user123' does not exist in this project"
+      );
+    });
+
+    it('should handle special characters in user ID', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.userProfile)
+      );
+
+      await client.users.get('user@example.com');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/user/user%40example.com');
+    });
+  });
+
+  describe('getBulk', () => {
+    it('should get multiple user profiles', async () => {
+      mockAxiosInstance.post.mockResolvedValue(
+        mockSuccessResponse(mockResponses.bulkUsersResponse)
+      );
+
+      const result = await client.users.getBulk(['user1', 'user2']);
+
+      expect(mockAxiosInstance.post).toHaveBeenCalledWith('/users/bulk', {
+        user_ids: ['user1', 'user2'],
+      });
+      expect(result).toEqual(mockResponses.bulkUsersResponse);
+      expect(result.users).toHaveLength(2);
+    });
+
+    it('should handle single user in bulk request', async () => {
+      mockAxiosInstance.post.mockResolvedValue(
+        mockSuccessResponse({ users: [mockResponses.userProfile] })
+      );
+
+      const result = await client.users.getBulk(['user_123']);
+
+      expect(result.users).toHaveLength(1);
+    });
+
+    it('should handle empty results', async () => {
+      mockAxiosInstance.post.mockResolvedValue(
+        mockSuccessResponse({ users: [] })
+      );
+
+      const result = await client.users.getBulk(['nonexistent1', 'nonexistent2']);
+
+      expect(result.users).toEqual([]);
+    });
+
+    it('should throw error for more than 100 users', async () => {
+      mockAxiosInstance.post.mockRejectedValue(
+        mockErrorResponse(400, 'Maximum 100 user IDs allowed')
+      );
+
+      const manyUsers = Array.from({ length: 101 }, (_, i) => `user_${i}`);
+
+      await expect(client.users.getBulk(manyUsers)).rejects.toThrow(
+        'Maximum 100 user IDs allowed'
+      );
+    });
+  });
+
+  describe('getBadges', () => {
+    it('should get user badges', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse({ badges: mockResponses.userProfile.badges })
+      );
+
+      const result = await client.users.getBadges('user_123');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/user/user_123/badges');
+      expect(result.badges).toHaveLength(1);
+      expect(result.badges[0].name).toBe('First Steps');
+    });
+
+    it('should handle user with no badges', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse({ badges: [] })
+      );
+
+      const result = await client.users.getBadges('user_new');
+
+      expect(result.badges).toEqual([]);
+    });
+
+    it('should throw 404 error when user not found', async () => {
+      mockAxiosInstance.get.mockRejectedValue(
+        mockErrorResponse(404, mockErrors.notFoundError.message)
+      );
+
+      await expect(client.users.getBadges('nonexistent_user')).rejects.toThrow(
+        "User 'user123' does not exist in this project"
+      );
+    });
+  });
+
+  describe('getRank', () => {
+    it('should get user rank with default timeframe', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.userRankResponse)
+      );
+
+      const result = await client.users.getRank('user_123');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/user/user_123/rank', {
+        params: { timeframe: 'all-time' },
+      });
+      expect(result).toEqual(mockResponses.userRankResponse);
+      expect(result.rank).toBe(42);
+    });
+
+    it('should get user rank with weekly timeframe', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.userRankResponse)
+      );
+
+      await client.users.getRank('user_123', 'weekly');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/user/user_123/rank', {
+        params: { timeframe: 'weekly' },
+      });
+    });
+
+    it('should get user rank with monthly timeframe', async () => {
+      mockAxiosInstance.get.mockResolvedValue(
+        mockSuccessResponse(mockResponses.userRankResponse)
+      );
+
+      await client.users.getRank('user_123', 'monthly');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/user/user_123/rank', {
+        params: { timeframe: 'monthly' },
+      });
+    });
+
+    it('should throw 404 error when user not found', async () => {
+      mockAxiosInstance.get.mockRejectedValue(
+        mockErrorResponse(404, mockErrors.notFoundError.message)
+      );
+
+      await expect(client.users.getRank('nonexistent_user')).rejects.toThrow(
+        "User 'user123' does not exist in this project"
+      );
+    });
+  });
+
+  describe('submitAnswers', () => {
+    it('should submit questionnaire answers', async () => {
+      mockAxiosInstance.post.mockResolvedValue(
+        mockSuccessResponse(mockResponses.answerSubmissionResponse)
+      );
+
+      const answers = [
+        { question_id: 'q1', answer_option_id: 'a1' },
+        { question_id: 'q2', answer_option_id: 'a2' },
+      ];
+
+      const result = await client.users.submitAnswers(
+        'user_123',
+        'questionnaire_id',
+        answers
+      );
+
+      expect(mockAxiosInstance.post).toHaveBeenCalledWith('/user/user_123/answers', {
+        questionnaire_id: 'questionnaire_id',
+        answers,
+      });
+      expect(result).toEqual(mockResponses.answerSubmissionResponse);
+      expect(result.status).toBe('accepted');
+    });
+
+    it('should handle single answer submission', async () => {
+      mockAxiosInstance.post.mockResolvedValue(
+        mockSuccessResponse(mockResponses.answerSubmissionResponse)
+      );
+
+      const answers = [{ question_id: 'q1', answer_option_id: 'a1' }];
+
+      await client.users.submitAnswers('user_123', 'questionnaire_id', answers);
+
+      expect(mockAxiosInstance.post).toHaveBeenCalled();
+    });
+
+    it('should throw error for invalid questionnaire ID', async () => {
+      mockAxiosInstance.post.mockRejectedValue(
+        mockErrorResponse(400, 'Invalid questionnaire ID')
+      );
+
+      const answers = [{ question_id: 'q1', answer_option_id: 'a1' }];
+
+      await expect(
+        client.users.submitAnswers('user_123', 'invalid_id', answers)
+      ).rejects.toThrow('Invalid questionnaire ID');
+    });
+
+    it('should throw error for empty answers array', async () => {
+      mockAxiosInstance.post.mockRejectedValue(
+        mockErrorResponse(400, 'Answers must be a non-empty array')
+      );
+
+      await expect(
+        client.users.submitAnswers('user_123', 'questionnaire_id', [])
+      ).rejects.toThrow('non-empty array');
+    });
+  });
+});

package/src/__tests__/utils/generators.ts

@@ -0,0 +1,80 @@
+import fc from 'fast-check';
+
+/**
+ * Property-based testing generators for SDK inputs
+ */
+
+export const arbitraries = {
+  // User ID: 1-255 characters, alphanumeric with some special chars
+  userId: () => fc.string({ minLength: 1, maxLength: 255 }).filter(s => s.trim().length > 0),
+  
+  // Event name: 1-100 characters
+  eventName: () => fc.string({ minLength: 1, maxLength: 100 }).filter(s => s.trim().length > 0),
+  
+  // Properties: any JSON-serializable object
+  properties: () => fc.dictionary(
+    fc.string({ minLength: 1, maxLength: 50 }),
+    fc.oneof(
+      fc.string(),
+      fc.integer(),
+      fc.double().filter(n => Number.isFinite(n)), // Exclude Infinity and NaN
+      fc.boolean(),
+      fc.constant(null)
+    )
+  ),
+  
+  // Timeframe: one of the valid values
+  timeframe: () => fc.constantFrom('all-time', 'weekly', 'monthly'),
+  
+  // Pagination parameters
+  pagination: () => fc.record({
+    page: fc.integer({ min: 1, max: 1000 }),
+    limit: fc.integer({ min: 1, max: 100 }),
+  }),
+  
+  // Aha score value: 1-5
+  ahaValue: () => fc.integer({ min: 1, max: 5 }),
+  
+  // Invalid Aha score value: outside 1-5 range
+  invalidAhaValue: () => fc.oneof(
+    fc.integer({ max: 0 }),
+    fc.integer({ min: 6 })
+  ),
+  
+  // UUID for leaderboard IDs
+  uuid: () => fc.uuid(),
+  
+  // Slug for questionnaires
+  slug: () => fc.string({ minLength: 1, maxLength: 100 })
+    .filter(s => /^[a-z0-9-]+$/.test(s)),
+  
+  // Array of user IDs for bulk operations
+  userIds: () => fc.array(
+    fc.string({ minLength: 1, maxLength: 255 }),
+    { minLength: 1, maxLength: 100 }
+  ),
+  
+  // Boolean for active_only filter
+  activeOnly: () => fc.boolean(),
+  
+  // Search query
+  searchQuery: () => fc.option(fc.string({ maxLength: 100 }), { nil: null }),
+  
+  // Base URL
+  baseUrl: () => fc.webUrl(),
+  
+  // Timeout in milliseconds
+  timeout: () => fc.integer({ min: 1000, max: 60000 }),
+  
+  // API key
+  apiKey: () => fc.string({ minLength: 10, maxLength: 100 }),
+  
+  // Questionnaire answers
+  questionnaireAnswers: () => fc.array(
+    fc.record({
+      question_id: fc.uuid(),
+      answer_option_id: fc.uuid(),
+    }),
+    { minLength: 1, maxLength: 20 }
+  ),
+};

package/src/__tests__/utils/mockClient.ts

@@ -0,0 +1,48 @@
+import { AxiosInstance } from 'axios';
+
+export interface MockAxiosInstance {
+  get: jest.Mock;
+  post: jest.Mock;
+  defaults: {
+    headers: {
+      common: Record<string, string>;
+    };
+  };
+  interceptors: {
+    request: { use: jest.Mock };
+    response: { use: jest.Mock };
+  };
+}
+
+export function createMockAxiosInstance(): MockAxiosInstance {
+  return {
+    get: jest.fn(),
+    post: jest.fn(),
+    defaults: {
+      headers: {
+        common: {},
+      },
+    },
+    interceptors: {
+      request: { use: jest.fn() },
+      response: { use: jest.fn() },
+    },
+  };
+}
+
+export function mockSuccessResponse<T>(data: T) {
+  return { data };
+}
+
+export function mockErrorResponse(status: number, message: string, details?: any) {
+  const error: any = new Error(message);
+  error.response = {
+    status,
+    data: {
+      error: message,
+      details,
+    },
+  };
+  error.isAxiosError = true;
+  return error;
+}