@rooguys/sdk 0.1.0 → 1.0.0

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

@@ -1,6 +1,12 @@
+import { AxiosResponse } from 'axios';
+import { Rooguys } from '../../index';
 export interface MockAxiosInstance {
     get: jest.Mock;
     post: jest.Mock;
+    put: jest.Mock;
+    patch: jest.Mock;
+    delete: jest.Mock;
+    request: jest.Mock;
     defaults: {
         headers: {
             common: Record<string, string>;
@@ -16,7 +22,63 @@ export interface MockAxiosInstance {
     };
 }
 export declare function createMockAxiosInstance(): MockAxiosInstance;
-export declare function mockSuccessResponse<T>(data: T): {
-    data: T;
+/**
+ * Create a mock Rooguys client with mocked HTTP client
+ * Returns both the client and the mock axios instance for setting up expectations
+ */
+export declare function createMockRooguysClient(apiKey?: string): {
+    client: Rooguys;
+    mockAxios: MockAxiosInstance;
 };
-export declare function mockErrorResponse(status: number, message: string, details?: any): any;
+/**
+ * Create a mock AxiosResponse with rate limit headers
+ */
+export declare function mockAxiosResponse<T>(data: T, status?: number, headers?: Record<string, string>): AxiosResponse<T>;
+/**
+ * Create a mock AxiosResponse for standardized API format
+ */
+export declare function mockStandardizedResponse<T>(data: T, requestId?: string, headers?: Record<string, string>): AxiosResponse<{
+    success: true;
+    data: T;
+    request_id: string;
+}>;
+/**
+ * Create a mock success response (legacy format - data directly in response)
+ */
+export declare function mockSuccessResponse<T>(data: T, headers?: Record<string, string>): AxiosResponse<T>;
+/**
+ * Create a mock error that mimics an Axios error
+ */
+export declare function mockErrorResponse(status: number, message: string, code?: string, details?: Array<{
+    field: string;
+    message: string;
+}>): any;
+/**
+ * Create a mock rate limit error
+ */
+export declare function mockRateLimitError(retryAfter?: number): any;
+/**
+ * Helper to set up mock for a successful request
+ * The mock axios instance uses request() method internally
+ */
+export declare function setupMockRequest<T>(mockAxios: MockAxiosInstance, responseData: T, headers?: Record<string, string>): void;
+/**
+ * Helper to set up mock for a failed request
+ */
+export declare function setupMockRequestError(mockAxios: MockAxiosInstance, status: number, message: string, code?: string, details?: Array<{
+    field: string;
+    message: string;
+}>): void;
+/**
+ * Get the last request config from mock axios
+ */
+export declare function getLastRequestConfig(mockAxios: MockAxiosInstance): any;
+/**
+ * Assert that a request was made with specific config
+ */
+export declare function expectRequestWith(mockAxios: MockAxiosInstance, expected: {
+    method?: string;
+    url?: string;
+    data?: any;
+    params?: any;
+}): void;

package/dist/__tests__/utils/mockClient.js

@@ -1,12 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMockAxiosInstance = createMockAxiosInstance;
+exports.createMockRooguysClient = createMockRooguysClient;
+exports.mockAxiosResponse = mockAxiosResponse;
+exports.mockStandardizedResponse = mockStandardizedResponse;
 exports.mockSuccessResponse = mockSuccessResponse;
 exports.mockErrorResponse = mockErrorResponse;
+exports.mockRateLimitError = mockRateLimitError;
+exports.setupMockRequest = setupMockRequest;
+exports.setupMockRequestError = setupMockRequestError;
+exports.getLastRequestConfig = getLastRequestConfig;
+exports.expectRequestWith = expectRequestWith;
+const index_1 = require("../../index");
 function createMockAxiosInstance() {
     return {
         get: jest.fn(),
         post: jest.fn(),
+        put: jest.fn(),
+        patch: jest.fn(),
+        delete: jest.fn(),
+        request: jest.fn(),
         defaults: {
             headers: {
                 common: {},
@@ -18,18 +31,144 @@ function createMockAxiosInstance() {
         },
     };
 }
-function mockSuccessResponse(data) {
-    return { data };
+/**
+ * Create a mock Rooguys client with mocked HTTP client
+ * Returns both the client and the mock axios instance for setting up expectations
+ */
+function createMockRooguysClient(apiKey = 'test-api-key') {
+    const client = new index_1.Rooguys(apiKey);
+    const mockAxios = createMockAxiosInstance();
+    // Access the internal HttpClient and replace its axios instance
+    const httpClient = client._httpClient;
+    httpClient.client = mockAxios;
+    return { client, mockAxios };
 }
-function mockErrorResponse(status, message, details) {
+/**
+ * Create a mock AxiosResponse with rate limit headers
+ */
+function mockAxiosResponse(data, status = 200, headers = {}) {
+    return {
+        data,
+        status,
+        statusText: status === 200 ? 'OK' : 'Error',
+        headers: {
+            'x-ratelimit-limit': '1000',
+            'x-ratelimit-remaining': '999',
+            'x-ratelimit-reset': String(Math.floor(Date.now() / 1000) + 3600),
+            ...headers,
+        },
+        config: {},
+    };
+}
+/**
+ * Create a mock AxiosResponse for standardized API format
+ */
+function mockStandardizedResponse(data, requestId = 'req-123', headers = {}) {
+    return mockAxiosResponse({
+        success: true,
+        data,
+        request_id: requestId,
+    }, 200, {
+        'x-request-id': requestId,
+        ...headers,
+    });
+}
+/**
+ * Create a mock success response (legacy format - data directly in response)
+ */
+function mockSuccessResponse(data, headers = {}) {
+    return mockAxiosResponse(data, 200, headers);
+}
+/**
+ * Create a mock error that mimics an Axios error
+ */
+function mockErrorResponse(status, message, code, details) {
     const error = new Error(message);
     error.response = {
         status,
         data: {
-            error: message,
-            details,
+            success: false,
+            error: {
+                message,
+                code: code || 'ERROR',
+                details,
+            },
+            request_id: 'req-error-123',
+        },
+        headers: {
+            'x-ratelimit-limit': '1000',
+            'x-ratelimit-remaining': '999',
+            'x-ratelimit-reset': String(Math.floor(Date.now() / 1000) + 3600),
+            'x-request-id': 'req-error-123',
+        },
+    };
+    error.isAxiosError = true;
+    return error;
+}
+/**
+ * Create a mock rate limit error
+ */
+function mockRateLimitError(retryAfter = 60) {
+    const error = new Error('Rate limit exceeded');
+    error.response = {
+        status: 429,
+        data: {
+            success: false,
+            error: {
+                message: 'Rate limit exceeded',
+                code: 'RATE_LIMIT_EXCEEDED',
+            },
+            request_id: 'req-ratelimit-123',
+        },
+        headers: {
+            'x-ratelimit-limit': '1000',
+            'x-ratelimit-remaining': '0',
+            'x-ratelimit-reset': String(Math.floor(Date.now() / 1000) + retryAfter),
+            'retry-after': String(retryAfter),
+            'x-request-id': 'req-ratelimit-123',
         },
     };
     error.isAxiosError = true;
     return error;
 }
+/**
+ * Helper to set up mock for a successful request
+ * The mock axios instance uses request() method internally
+ */
+function setupMockRequest(mockAxios, responseData, headers = {}) {
+    mockAxios.request.mockResolvedValue(mockAxiosResponse(responseData, 200, headers));
+}
+/**
+ * Helper to set up mock for a failed request
+ */
+function setupMockRequestError(mockAxios, status, message, code, details) {
+    mockAxios.request.mockRejectedValue(mockErrorResponse(status, message, code, details));
+}
+/**
+ * Get the last request config from mock axios
+ */
+function getLastRequestConfig(mockAxios) {
+    const calls = mockAxios.request.mock.calls;
+    if (calls.length === 0)
+        return null;
+    return calls[calls.length - 1][0];
+}
+/**
+ * Assert that a request was made with specific config
+ */
+function expectRequestWith(mockAxios, expected) {
+    const lastConfig = getLastRequestConfig(mockAxios);
+    expect(lastConfig).toBeTruthy();
+    if (expected.method) {
+        expect(lastConfig.method).toBe(expected.method);
+    }
+    if (expected.url) {
+        expect(lastConfig.url).toBe(expected.url);
+    }
+    if (expected.data) {
+        expect(lastConfig.data).toEqual(expected.data);
+    }
+    if (expected.params) {
+        expect(lastConfig.params).toEqual(expected.params);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Rooguys Node.js SDK Error Classes
+ * Typed error classes for different API error scenarios
+ */
+/**
+ * Field-level error detail
+ */
+export interface FieldError {
+    field: string;
+    message: string;
+}
+/**
+ * Base error options
+ */
+export interface RooguysErrorOptions {
+    code?: string;
+    requestId?: string | null;
+    statusCode?: number;
+}
+/**
+ * Base error class for all Rooguys SDK errors
+ */
+export declare class RooguysError extends Error {
+    readonly code: string;
+    readonly requestId: string | null;
+    readonly statusCode: number;
+    constructor(message: string, { code, requestId, statusCode }?: RooguysErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Validation error options
+ */
+export interface ValidationErrorOptions extends RooguysErrorOptions {
+    fieldErrors?: FieldError[] | null;
+}
+/**
+ * Validation error (HTTP 400)
+ * Thrown when request validation fails
+ */
+export declare class ValidationError extends RooguysError {
+    readonly fieldErrors: FieldError[] | null;
+    constructor(message: string, { code, requestId, fieldErrors }?: ValidationErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Authentication error (HTTP 401)
+ * Thrown when API key is invalid or missing
+ */
+export declare class AuthenticationError extends RooguysError {
+    constructor(message: string, { code, requestId }?: RooguysErrorOptions);
+}
+/**
+ * Forbidden error (HTTP 403)
+ * Thrown when access is denied
+ */
+export declare class ForbiddenError extends RooguysError {
+    constructor(message: string, { code, requestId }?: RooguysErrorOptions);
+}
+/**
+ * Not found error (HTTP 404)
+ * Thrown when requested resource doesn't exist
+ */
+export declare class NotFoundError extends RooguysError {
+    constructor(message: string, { code, requestId }?: RooguysErrorOptions);
+}
+/**
+ * Conflict error (HTTP 409)
+ * Thrown when resource already exists or state conflict
+ */
+export declare class ConflictError extends RooguysError {
+    constructor(message: string, { code, requestId }?: RooguysErrorOptions);
+}
+/**
+ * Rate limit error options
+ */
+export interface RateLimitErrorOptions extends RooguysErrorOptions {
+    retryAfter?: number;
+}
+/**
+ * Rate limit error (HTTP 429)
+ * Thrown when rate limit is exceeded
+ */
+export declare class RateLimitError extends RooguysError {
+    readonly retryAfter: number;
+    constructor(message: string, { code, requestId, retryAfter }?: RateLimitErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Server error (HTTP 500+)
+ * Thrown when server encounters an error
+ */
+export declare class ServerError extends RooguysError {
+    constructor(message: string, { code, requestId, statusCode }?: RooguysErrorOptions);
+}
+/**
+ * Error response body structure
+ */
+export interface ErrorResponseBody {
+    error?: {
+        message?: string;
+        code?: string;
+        details?: FieldError[];
+    } | string;
+    message?: string;
+    code?: string;
+    details?: FieldError[];
+}
+/**
+ * Response headers for error mapping
+ */
+export interface ErrorResponseHeaders {
+    'retry-after'?: string;
+    'Retry-After'?: string;
+}
+/**
+ * Map HTTP status code to appropriate error class
+ * @param status - HTTP status code
+ * @param errorBody - Error response body
+ * @param requestId - Request ID from response
+ * @param headers - Response headers
+ * @returns Appropriate error instance
+ */
+export declare function mapStatusToError(status: number, errorBody: ErrorResponseBody | null, requestId: string | null, headers?: ErrorResponseHeaders): RooguysError;

package/dist/errors.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Rooguys Node.js SDK Error Classes
+ * Typed error classes for different API error scenarios
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerError = exports.RateLimitError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.AuthenticationError = exports.ValidationError = exports.RooguysError = void 0;
+exports.mapStatusToError = mapStatusToError;
+/**
+ * Base error class for all Rooguys SDK errors
+ */
+class RooguysError extends Error {
+    constructor(message, { code = 'UNKNOWN_ERROR', requestId = null, statusCode = 500 } = {}) {
+        super(message);
+        this.name = 'RooguysError';
+        this.code = code;
+        this.requestId = requestId;
+        this.statusCode = statusCode;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            requestId: this.requestId,
+            statusCode: this.statusCode,
+        };
+    }
+}
+exports.RooguysError = RooguysError;
+/**
+ * Validation error (HTTP 400)
+ * Thrown when request validation fails
+ */
+class ValidationError extends RooguysError {
+    constructor(message, { code = 'VALIDATION_ERROR', requestId = null, fieldErrors = null } = {}) {
+        super(message, { code, requestId, statusCode: 400 });
+        this.name = 'ValidationError';
+        this.fieldErrors = fieldErrors;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            fieldErrors: this.fieldErrors,
+        };
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Authentication error (HTTP 401)
+ * Thrown when API key is invalid or missing
+ */
+class AuthenticationError extends RooguysError {
+    constructor(message, { code = 'AUTHENTICATION_ERROR', requestId = null } = {}) {
+        super(message, { code, requestId, statusCode: 401 });
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+/**
+ * Forbidden error (HTTP 403)
+ * Thrown when access is denied
+ */
+class ForbiddenError extends RooguysError {
+    constructor(message, { code = 'FORBIDDEN', requestId = null } = {}) {
+        super(message, { code, requestId, statusCode: 403 });
+        this.name = 'ForbiddenError';
+    }
+}
+exports.ForbiddenError = ForbiddenError;
+/**
+ * Not found error (HTTP 404)
+ * Thrown when requested resource doesn't exist
+ */
+class NotFoundError extends RooguysError {
+    constructor(message, { code = 'NOT_FOUND', requestId = null } = {}) {
+        super(message, { code, requestId, statusCode: 404 });
+        this.name = 'NotFoundError';
+    }
+}
+exports.NotFoundError = NotFoundError;
+/**
+ * Conflict error (HTTP 409)
+ * Thrown when resource already exists or state conflict
+ */
+class ConflictError extends RooguysError {
+    constructor(message, { code = 'CONFLICT', requestId = null } = {}) {
+        super(message, { code, requestId, statusCode: 409 });
+        this.name = 'ConflictError';
+    }
+}
+exports.ConflictError = ConflictError;
+/**
+ * Rate limit error (HTTP 429)
+ * Thrown when rate limit is exceeded
+ */
+class RateLimitError extends RooguysError {
+    constructor(message, { code = 'RATE_LIMIT_EXCEEDED', requestId = null, retryAfter = 60 } = {}) {
+        super(message, { code, requestId, statusCode: 429 });
+        this.name = 'RateLimitError';
+        this.retryAfter = retryAfter;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            retryAfter: this.retryAfter,
+        };
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * Server error (HTTP 500+)
+ * Thrown when server encounters an error
+ */
+class ServerError extends RooguysError {
+    constructor(message, { code = 'SERVER_ERROR', requestId = null, statusCode = 500 } = {}) {
+        super(message, { code, requestId, statusCode });
+        this.name = 'ServerError';
+    }
+}
+exports.ServerError = ServerError;
+/**
+ * Map HTTP status code to appropriate error class
+ * @param status - HTTP status code
+ * @param errorBody - Error response body
+ * @param requestId - Request ID from response
+ * @param headers - Response headers
+ * @returns Appropriate error instance
+ */
+function mapStatusToError(status, errorBody, requestId, headers = {}) {
+    const errorObj = typeof (errorBody === null || errorBody === void 0 ? void 0 : errorBody.error) === 'object' ? errorBody.error : null;
+    const message = (errorObj === null || errorObj === void 0 ? void 0 : errorObj.message) ||
+        (typeof (errorBody === null || errorBody === void 0 ? void 0 : errorBody.error) === 'string' ? errorBody.error : null) ||
+        (errorBody === null || errorBody === void 0 ? void 0 : errorBody.message) ||
+        'An error occurred';
+    const code = (errorObj === null || errorObj === void 0 ? void 0 : errorObj.code) || (errorBody === null || errorBody === void 0 ? void 0 : errorBody.code) || 'UNKNOWN_ERROR';
+    const fieldErrors = (errorObj === null || errorObj === void 0 ? void 0 : errorObj.details) || (errorBody === null || errorBody === void 0 ? void 0 : errorBody.details) || null;
+    switch (status) {
+        case 400:
+            return new ValidationError(message, { code, requestId, fieldErrors });
+        case 401:
+            return new AuthenticationError(message, { code, requestId });
+        case 403:
+            return new ForbiddenError(message, { code, requestId });
+        case 404:
+            return new NotFoundError(message, { code, requestId });
+        case 409:
+            return new ConflictError(message, { code, requestId });
+        case 429: {
+            const retryAfter = parseInt(headers['retry-after'] || headers['Retry-After'] || '60', 10);
+            return new RateLimitError(message, { code, requestId, retryAfter });
+        }
+        default:
+            if (status >= 500) {
+                return new ServerError(message, { code, requestId, statusCode: status });
+            }
+            return new RooguysError(message, { code, requestId, statusCode: status });
+    }
+}

package/dist/http-client.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Rooguys Node.js SDK HTTP Client
+ * Handles standardized response format, rate limit headers, and error mapping
+ */
+import { ErrorResponseBody } from './errors';
+/**
+ * Rate limit information extracted from response headers
+ */
+export interface RateLimitInfo {
+    /** Maximum requests allowed in the window */
+    limit: number;
+    /** Remaining requests in the current window */
+    remaining: number;
+    /** Unix timestamp when the limit resets */
+    reset: number;
+}
+/**
+ * Cache metadata from API responses
+ */
+export interface CacheMetadata {
+    /** When the data was cached */
+    cachedAt: Date | null;
+    /** Time-to-live in seconds */
+    ttl: number;
+}
+/**
+ * Pagination information
+ */
+export interface Pagination {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+/**
+ * API response wrapper with metadata
+ */
+export interface ApiResponse<T> {
+    /** Response data */
+    data: T;
+    /** Request ID for debugging */
+    requestId: string | null;
+    /** Rate limit information */
+    rateLimit: RateLimitInfo;
+    /** Pagination info if present */
+    pagination?: Pagination | null;
+    /** Cache metadata if present */
+    cacheMetadata?: CacheMetadata | null;
+}
+/**
+ * Request configuration options
+ */
+export interface RequestConfig {
+    /** HTTP method */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** API endpoint path */
+    path: string;
+    /** Query parameters */
+    params?: Record<string, string | number | boolean | undefined | null>;
+    /** Request body */
+    body?: unknown;
+    /** Additional headers */
+    headers?: Record<string, string>;
+    /** Idempotency key for POST requests */
+    idempotencyKey?: string;
+    /** Request timeout in ms */
+    timeout?: number;
+}
+/**
+ * HTTP Client options
+ */
+export interface HttpClientOptions {
+    /** Base URL for API */
+    baseUrl?: string;
+    /** Request timeout in ms */
+    timeout?: number;
+    /** Callback when rate limit is 80% consumed */
+    onRateLimitWarning?: ((rateLimit: RateLimitInfo) => void) | null;
+    /** Enable auto-retry for rate-limited requests */
+    autoRetry?: boolean;
+    /** Maximum retry attempts for rate limits */
+    maxRetries?: number;
+    /** Base delay for retries in ms */
+    retryDelay?: number;
+}
+/**
+ * Parsed response body result
+ */
+interface ParsedResponseBody<T> {
+    data?: T;
+    error?: ErrorResponseBody['error'];
+    pagination?: Pagination | null;
+    requestId?: string | null;
+}
+/**
+ * Extract rate limit information from response headers
+ * @param headers - Response headers (axios format)
+ * @returns Rate limit info
+ */
+export declare function extractRateLimitInfo(headers: Record<string, string | undefined>): RateLimitInfo;
+/**
+ * Extract request ID from response headers or body
+ * @param headers - Response headers
+ * @param body - Response body
+ * @returns Request ID or null
+ */
+export declare function extractRequestId(headers: Record<string, string | undefined>, body: unknown): string | null;
+/**
+ * Parse standardized API response format
+ * Handles both new format { success: true, data: {...} } and legacy format
+ * @param body - Response body
+ * @returns Parsed response with data and metadata
+ */
+export declare function parseResponseBody<T>(body: unknown): ParsedResponseBody<T>;
+/**
+ * HTTP Client class for making API requests
+ */
+export declare class HttpClient {
+    private client;
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private onRateLimitWarning;
+    private autoRetry;
+    private maxRetries;
+    private retryDelay;
+    constructor(apiKey: string, options?: HttpClientOptions);
+    /**
+     * Sleep for a specified duration
+     * @param ms - Milliseconds to sleep
+     */
+    private sleep;
+    /**
+     * Build query string from params object
+     * @param params - Query parameters
+     * @returns Cleaned params object
+     */
+    private buildParams;
+    /**
+     * Make an HTTP request with optional auto-retry for rate limits
+     * @param config - Request configuration
+     * @param retryCount - Current retry attempt (internal use)
+     * @returns API response with data and metadata
+     */
+    request<T>(config: RequestConfig, retryCount?: number): Promise<ApiResponse<T>>;
+    /**
+     * Convenience method for GET requests
+     */
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined | null>, options?: Partial<RequestConfig>): Promise<ApiResponse<T>>;
+    /**
+     * Convenience method for POST requests
+     */
+    post<T>(path: string, body?: unknown, options?: Partial<RequestConfig>): Promise<ApiResponse<T>>;
+    /**
+     * Convenience method for PUT requests
+     */
+    put<T>(path: string, body?: unknown, options?: Partial<RequestConfig>): Promise<ApiResponse<T>>;
+    /**
+     * Convenience method for PATCH requests
+     */
+    patch<T>(path: string, body?: unknown, options?: Partial<RequestConfig>): Promise<ApiResponse<T>>;
+    /**
+     * Convenience method for DELETE requests
+     */
+    delete<T>(path: string, options?: Partial<RequestConfig>): Promise<ApiResponse<T>>;
+}
+export {};