@rooguys/sdk 0.1.0

package/dist/__tests__/fixtures/responses.js

@@ -0,0 +1,311 @@
+"use strict";
+/**
+ * Mock API response fixtures for testing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockErrors = exports.mockResponses = void 0;
+exports.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,
+        },
+    },
+};
+exports.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',
+            },
+        ],
+    },
+};

package/dist/__tests__/utils/generators.d.ts

@@ -0,0 +1,28 @@
+import fc from 'fast-check';
+/**
+ * Property-based testing generators for SDK inputs
+ */
+export declare const arbitraries: {
+    userId: () => fc.Arbitrary<string>;
+    eventName: () => fc.Arbitrary<string>;
+    properties: () => fc.Arbitrary<Record<string, string | number | boolean | null>>;
+    timeframe: () => fc.Arbitrary<string>;
+    pagination: () => fc.Arbitrary<{
+        page: number;
+        limit: number;
+    }>;
+    ahaValue: () => fc.Arbitrary<number>;
+    invalidAhaValue: () => fc.Arbitrary<number>;
+    uuid: () => fc.Arbitrary<string>;
+    slug: () => fc.Arbitrary<string>;
+    userIds: () => fc.Arbitrary<string[]>;
+    activeOnly: () => fc.Arbitrary<boolean>;
+    searchQuery: () => fc.Arbitrary<string | null>;
+    baseUrl: () => fc.Arbitrary<string>;
+    timeout: () => fc.Arbitrary<number>;
+    apiKey: () => fc.Arbitrary<string>;
+    questionnaireAnswers: () => fc.Arbitrary<{
+        question_id: string;
+        answer_option_id: string;
+    }[]>;
+};

package/dist/__tests__/utils/generators.js

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

package/dist/__tests__/utils/mockClient.d.ts

@@ -0,0 +1,22 @@
+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 declare function createMockAxiosInstance(): MockAxiosInstance;
+export declare function mockSuccessResponse<T>(data: T): {
+    data: T;
+};
+export declare function mockErrorResponse(status: number, message: string, details?: any): any;

package/dist/__tests__/utils/mockClient.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMockAxiosInstance = createMockAxiosInstance;
+exports.mockSuccessResponse = mockSuccessResponse;
+exports.mockErrorResponse = mockErrorResponse;
+function createMockAxiosInstance() {
+    return {
+        get: jest.fn(),
+        post: jest.fn(),
+        defaults: {
+            headers: {
+                common: {},
+            },
+        },
+        interceptors: {
+            request: { use: jest.fn() },
+            response: { use: jest.fn() },
+        },
+    };
+}
+function mockSuccessResponse(data) {
+    return { data };
+}
+function mockErrorResponse(status, message, details) {
+    const error = new Error(message);
+    error.response = {
+        status,
+        data: {
+            error: message,
+            details,
+        },
+    };
+    error.isAxiosError = true;
+    return error;
+}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { RooguysOptions, TrackEventResponse, UserProfile, UserBadge, UserRank, LeaderboardResult, AnswerSubmission, AhaDeclarationResult, AhaScoreResult, BadgeListResult, LevelListResult, Questionnaire, LeaderboardListResult } from './types';
+export declare class Rooguys {
+    private apiKey;
+    private client;
+    constructor(apiKey: string, options?: RooguysOptions);
+    events: {
+        track: (eventName: string, userId: string, properties?: Record<string, any>, options?: {
+            includeProfile?: boolean;
+        }) => Promise<TrackEventResponse>;
+    };
+    users: {
+        get: (userId: string) => Promise<UserProfile>;
+        getBulk: (userIds: string[]) => Promise<{
+            users: UserProfile[];
+        }>;
+        getBadges: (userId: string) => Promise<{
+            badges: UserBadge[];
+        }>;
+        getRank: (userId: string, timeframe?: "all-time" | "weekly" | "monthly") => Promise<UserRank>;
+        submitAnswers: (userId: string, questionnaireId: string, answers: AnswerSubmission[]) => Promise<{
+            status: string;
+            message: string;
+        }>;
+    };
+    leaderboards: {
+        getGlobal: (timeframe?: "all-time" | "weekly" | "monthly", page?: number, limit?: number) => Promise<LeaderboardResult>;
+        list: (page?: number, limit?: number, search?: string) => Promise<LeaderboardListResult>;
+        getCustom: (leaderboardId: string, page?: number, limit?: number, search?: string) => Promise<LeaderboardResult>;
+        getUserRank: (leaderboardId: string, userId: string) => Promise<UserRank>;
+    };
+    badges: {
+        list: (page?: number, limit?: number, activeOnly?: boolean) => Promise<BadgeListResult>;
+    };
+    levels: {
+        list: (page?: number, limit?: number) => Promise<LevelListResult>;
+    };
+    questionnaires: {
+        get: (slug: string) => Promise<Questionnaire>;
+        getActive: () => Promise<Questionnaire>;
+    };
+    aha: {
+        declare: (userId: string, value: number) => Promise<AhaDeclarationResult>;
+        getUserScore: (userId: string) => Promise<AhaScoreResult>;
+    };
+    private handleError;
+}
+export default Rooguys;