@rooguys/js 0.1.0

package/README.md

@@ -0,0 +1,277 @@
+# Rooguys Javascript SDK
+
+The official Browser SDK for the Rooguys Gamification API. Lightweight and dependency-free (uses native `fetch`).
+
+## Installation
+
+### NPM
+```bash
+npm install @rooguys/js
+```
+
+### Direct Import (ES Modules)
+```javascript
+import Rooguys from './path/to/sdk/index.js';
+```
+
+## Initialization
+
+```javascript
+import Rooguys from '@rooguys/js';
+
+const client = new Rooguys('YOUR_API_KEY', {
+  baseUrl: 'https://api.rooguys.com/v1',
+});
+```
+
+## Usage Examples
+
+### 1. Track an Event
+
+```javascript
+client.events.track('level_completed', 'user_123', { difficulty: 'hard' })
+  .then(response => {
+    console.log('Event tracked:', response);
+  })
+  .catch(console.error);
+```
+
+### 2. Get User Profile
+
+```javascript
+async function showProfile(userId) {
+  try {
+    const user = await client.users.get(userId);
+    document.getElementById('points').innerText = user.points;
+    document.getElementById('level').innerText = user.level?.name || 'No Level';
+  } catch (error) {
+    console.error('Failed to load profile:', error);
+  }
+}
+```
+
+### 3. Display Leaderboard
+
+```javascript
+async function loadLeaderboard() {
+  const data = await client.leaderboards.getGlobal('weekly');
+  
+  const list = document.getElementById('leaderboard');
+  list.innerHTML = data.rankings
+    .map(r => `<li>#${r.rank} ${r.user_id}: ${r.points}</li>`)
+    .join('');
+}
+```
+
+### 4. List Custom Leaderboards
+
+```javascript
+// Get all available leaderboards
+const leaderboards = await client.leaderboards.list(1, 20);
+
+leaderboards.data.forEach(lb => {
+  console.log(`${lb.name}: ${lb.description}`);
+});
+```
+
+### 5. Get Custom Leaderboard Rankings
+
+```javascript
+// Get rankings for a specific leaderboard
+const customLb = await client.leaderboards.getCustom('leaderboard_id', 1, 10);
+
+console.log(`Leaderboard: ${customLb.name}`);
+customLb.rankings.forEach(entry => {
+  console.log(`#${entry.rank} - ${entry.user_id}: ${entry.points} pts`);
+});
+```
+
+### 6. Get User Rank in Custom Leaderboard
+
+```javascript
+const rank = await client.leaderboards.getUserRank('leaderboard_id', 'user_123');
+
+console.log(`User rank: #${rank.rank} out of ${rank.total_users}`);
+```
+
+### 7. List Badges
+
+```javascript
+// Get all active badges
+const badges = await client.badges.list(1, 50, true);
+
+badges.data.forEach(badge => {
+  console.log(`${badge.name}: ${badge.description}`);
+});
+```
+
+### 8. List Levels
+
+```javascript
+const levels = await client.levels.list();
+
+levels.data.forEach(level => {
+  console.log(`Level ${level.level_number}: ${level.name} (${level.points_required} pts)`);
+});
+```
+
+### 9. Get Questionnaire
+
+```javascript
+// Get questionnaire by slug
+const questionnaire = await client.questionnaires.get('onboarding-survey');
+
+console.log(`Title: ${questionnaire.title}`);
+questionnaire.questions.forEach(q => {
+  console.log(`Q: ${q.text}`);
+});
+```
+
+### 10. Get Active Questionnaire
+
+```javascript
+const activeQuestionnaire = await client.questionnaires.getActive();
+
+if (activeQuestionnaire) {
+  console.log(`Active: ${activeQuestionnaire.title}`);
+}
+```
+
+### 11. Aha Score - Declare User Activation
+
+Track when users reach their "Aha Moment" with declarative scores (1-5).
+
+```javascript
+// Declare that a user has reached an activation milestone
+const result = await client.aha.declare('user_123', 4);
+
+console.log(result.message); // "Aha score declared successfully"
+```
+
+### 12. Aha Score - Get User Score
+
+Retrieve a user's Aha Score, including declarative and inferred scores.
+
+```javascript
+const ahaScore = await client.aha.getUserScore('user_123');
+
+console.log(`Current Score: ${ahaScore.data.current_score}`);
+console.log(`Status: ${ahaScore.data.status}`); // 'not_started', 'progressing', or 'activated'
+console.log(`Declarative Score: ${ahaScore.data.declarative_score}`);
+console.log(`Inferred Score: ${ahaScore.data.inferred_score}`);
+
+// Access history
+if (ahaScore.data.history.initial) {
+  console.log(`Initial Score: ${ahaScore.data.history.initial}`);
+  console.log(`Initial Date: ${ahaScore.data.history.initial_date}`);
+}
+```
+
+## API Reference
+
+### Events
+
+- `track(eventName, userId, properties, options)` - Track a user event
+
+### Users
+
+- `get(userId)` - Get user profile
+- `getBulk(userIds)` - Get multiple user profiles
+- `getBadges(userId)` - Get user's badges
+- `getRank(userId, timeframe)` - Get user's rank in global leaderboard
+- `submitAnswers(userId, questionnaireId, answers)` - Submit questionnaire answers
+
+### Leaderboards
+
+- `getGlobal(timeframe, page, limit)` - Get global leaderboard rankings
+- `list(page, limit, search)` - List all available leaderboards
+- `getCustom(leaderboardId, page, limit, search)` - Get custom leaderboard rankings
+- `getUserRank(leaderboardId, userId)` - Get user's rank in a custom leaderboard
+
+### Badges
+
+- `list(page, limit, activeOnly)` - List all badges
+
+### Levels
+
+- `list(page, limit)` - List all levels
+
+### Questionnaires
+
+- `get(slug)` - Get questionnaire by slug
+- `getActive()` - Get the currently active questionnaire
+
+### Aha Score
+
+- `declare(userId, value)` - Declare a user's Aha Moment score (value must be between 1-5)
+- `getUserScore(userId)` - Retrieve a user's current Aha Score and history
+
+## Error Handling
+
+```javascript
+try {
+  await client.users.get('unknown_user');
+} catch (error) {
+  console.error('API Error:', error.message);
+}
+```
+
+### Validation Errors
+
+```javascript
+try {
+  // Invalid Aha Score value (must be 1-5)
+  await client.aha.declare('user_123', 10);
+} catch (error) {
+  console.error(error.message); // "Aha score value must be between 1 and 5"
+}
+```
+
+## Testing
+
+The SDK includes comprehensive test coverage with both unit tests and property-based tests.
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Test Coverage
+
+```bash
+npm run test:coverage
+```
+
+The SDK maintains >90% test coverage across all modules, including:
+- Unit tests for all API methods
+- Property-based tests using fast-check
+- Error handling and edge case validation
+- Concurrent request handling
+
+### Property-Based Testing
+
+The SDK uses [fast-check](https://github.com/dubzzz/fast-check) for property-based testing to verify correctness across a wide range of inputs:
+
+```javascript
+// Example: Verifying response parsing preservation
+fc.assert(
+  fc.property(
+    fc.jsonValue(),
+    async (responseData) => {
+      // Test that any valid JSON response is parsed correctly
+      // and data structure is preserved
+    }
+  ),
+  { numRuns: 100 }
+);
+```
+
+## Requirements
+
+This SDK requires a browser environment with support for:
+- `fetch` API
+- `Promise`
+- `AbortController` (for timeouts)
+
+Most modern browsers support these features.

package/jest.config.js

@@ -0,0 +1,22 @@
+export default {
+  testEnvironment: 'jsdom',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.test.js'],
+  transform: {},
+  collectCoverageFrom: [
+    'src/**/*.js',
+    '!src/**/*.test.js',
+    '!src/**/__tests__/**',
+  ],
+  coverageThreshold: {
+    global: {
+      lines: 90,
+      branches: 85,
+      functions: 90,
+      statements: 90,
+    },
+  },
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.js'],
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "@rooguys/js",
+    "version": "0.1.0",
+    "description": "Official Browser SDK for Rooguys API",
+    "type": "module",
+    "main": "src/index.js",
+    "module": "src/index.js",
+    "scripts": {
+        "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+        "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch",
+        "test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage"
+    },
+    "keywords": [
+        "rooguys",
+        "sdk",
+        "browser",
+        "gamification"
+    ],
+    "author": "mowamed",
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "@types/jest": "^29.5.0",
+        "fast-check": "^3.15.0",
+        "jest": "^29.7.0",
+        "jest-environment-jsdom": "^29.7.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Rooguys/rooguys-browser-sdk.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Rooguys/rooguys-browser-sdk/issues"
+    },
+    "homepage": "https://github.com/Rooguys/rooguys-browser-sdk#readme"
+}

package/src/__tests__/fixtures/responses.js

@@ -0,0 +1,330 @@
+/**
+ * Mock API response fixtures for testing
+ */
+
+export const mockResponses = {
+  userProfile: {
+    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: [
+      {
+        id: 'badge1',
+        name: 'First Steps',
+        description: 'Completed first action',
+        icon_url: 'https://example.com/badge1.png',
+        earned_at: '2024-01-01T00:00:00Z',
+      },
+    ],
+  },
+
+  trackEventResponse: {
+    status: 'queued',
+    message: 'Event accepted for processing',
+  },
+
+  trackEventWithProfileResponse: {
+    status: 'queued',
+    message: 'Event accepted for processing',
+    profile: {
+      user_id: 'user123',
+      points: 110,
+      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: 390,
+      },
+      metrics: {},
+      badges: [],
+    },
+  },
+
+  leaderboardResponse: {
+    timeframe: 'all-time',
+    page: 1,
+    limit: 50,
+    total: 100,
+    rankings: [
+      {
+        rank: 1,
+        user_id: 'user1',
+        points: 1000,
+        level: {
+          id: 'level3',
+          name: 'Gold',
+          level_number: 3,
+        },
+      },
+      {
+        rank: 2,
+        user_id: 'user2',
+        points: 900,
+        level: {
+          id: 'level2',
+          name: 'Silver',
+          level_number: 2,
+        },
+      },
+    ],
+  },
+
+  userRankResponse: {
+    user_id: 'user123',
+    rank: 42,
+    points: 850,
+    total_users: 1000,
+  },
+
+  badgesListResponse: {
+    badges: [
+      {
+        id: 'badge1',
+        name: 'First Steps',
+        description: 'Completed first action',
+        icon_url: 'https://example.com/badge1.png',
+        is_active: true,
+        unlock_criteria: {
+          metric: 'actions',
+          value: 1,
+        },
+      },
+    ],
+    pagination: {
+      page: 1,
+      limit: 50,
+      total: 10,
+      totalPages: 1,
+    },
+  },
+
+  levelsListResponse: {
+    levels: [
+      {
+        id: 'level1',
+        name: 'Bronze',
+        level_number: 1,
+        points_required: 0,
+        description: 'Starting level',
+        icon_url: 'https://example.com/bronze.png',
+      },
+      {
+        id: 'level2',
+        name: 'Silver',
+        level_number: 2,
+        points_required: 500,
+        description: 'Intermediate level',
+        icon_url: 'https://example.com/silver.png',
+      },
+    ],
+    pagination: {
+      page: 1,
+      limit: 50,
+      total: 5,
+      totalPages: 1,
+    },
+  },
+
+  questionnaireResponse: {
+    id: 'questionnaire1',
+    slug: 'user-persona',
+    title: 'User Persona Quiz',
+    description: 'Determine your user persona',
+    is_active: true,
+    questions: [
+      {
+        id: 'q1',
+        text: 'What motivates you?',
+        order: 1,
+        answer_options: [
+          {
+            id: 'a1',
+            text: 'Competition',
+            persona_weights: { Competitor: 1 },
+          },
+          {
+            id: 'a2',
+            text: 'Exploration',
+            persona_weights: { Explorer: 1 },
+          },
+        ],
+      },
+    ],
+  },
+
+  bulkUsersResponse: {
+    users: [
+      {
+        user_id: 'user1',
+        points: 100,
+        persona: null,
+        level: null,
+        next_level: null,
+        metrics: {},
+        badges: [],
+      },
+      {
+        user_id: 'user2',
+        points: 200,
+        persona: 'Achiever',
+        level: {
+          id: 'level1',
+          name: 'Bronze',
+          level_number: 1,
+          points_required: 0,
+        },
+        next_level: null,
+        metrics: {},
+        badges: [],
+      },
+    ],
+  },
+
+  ahaScoreResponse: {
+    success: true,
+    data: {
+      user_id: 'user123',
+      current_score: 75,
+      declarative_score: 80,
+      inferred_score: 70,
+      status: 'activated',
+      history: {
+        initial: 50,
+        initial_date: '2024-01-01T00:00:00Z',
+        previous: 70,
+      },
+    },
+  },
+
+  ahaDeclarationResponse: {
+    success: true,
+    message: 'Declarative score recorded. Calculation in progress.',
+  },
+
+  answerSubmissionResponse: {
+    status: 'accepted',
+    message: 'Answers queued for processing',
+  },
+
+  leaderboardsListResponse: {
+    leaderboards: [
+      {
+        id: 'lb1',
+        name: 'Top Players',
+        description: 'Overall top players',
+        type: 'POINTS',
+        timeframe: 'all-time',
+        is_active: true,
+        created_at: '2024-01-01T00:00:00Z',
+      },
+    ],
+    pagination: {
+      page: 1,
+      limit: 50,
+      total: 5,
+      totalPages: 1,
+    },
+  },
+
+  customLeaderboardResponse: {
+    leaderboard: {
+      id: 'lb1',
+      name: 'Top Players',
+      description: 'Overall top players',
+      type: 'POINTS',
+      timeframe: 'all-time',
+      is_active: true,
+      created_at: '2024-01-01T00:00:00Z',
+    },
+    rankings: [
+      {
+        rank: 1,
+        user_id: 'user1',
+        points: 1000,
+        level: null,
+      },
+    ],
+    pagination: {
+      page: 1,
+      limit: 50,
+      total: 10,
+      totalPages: 1,
+    },
+  },
+};
+
+export const mockErrors = {
+  validationError: {
+    error: 'Validation failed',
+    details: [
+      {
+        field: 'user_id',
+        message: 'User ID is required',
+      },
+    ],
+  },
+
+  notFoundError: {
+    error: 'User not found',
+    message: "User 'user123' does not exist in this project",
+  },
+
+  serverError: {
+    error: 'Internal server error',
+  },
+
+  queueFullError: {
+    error: 'Service unavailable',
+    message: 'Event queue is full. Please retry later.',
+  },
+
+  unauthorizedError: {
+    error: 'Unauthorized',
+    message: 'Invalid or missing API key',
+  },
+
+  invalidTimeframeError: {
+    error: 'Invalid timeframe',
+    message: "Timeframe must be one of: all-time, weekly, monthly",
+  },
+
+  invalidPaginationError: {
+    error: 'Invalid limit parameter',
+    message: 'Limit must be between 1 and 100',
+  },
+
+  ahaValueError: {
+    error: 'Validation failed',
+    details: [
+      {
+        field: 'value',
+        message: 'value must be an integer between 1 and 5',
+      },
+    ],
+  },
+};