braiins-api-mapper

Maps Braiins Pool API endpoints to MCP tool implementations with proper authentication, rate limiting, retry logic, and error handling patterns.

الانتقال إلى التثبيت

المستودع: aibot88/sec_skill_store
آخر نشاط في المصدر: ٢٧ مايو ٢٠٢٦ في ٠٣:٤٧
لغة SKILL.md المكتشفة: الإنجليزية
النجوم: ٣
التفرعات: ٠

خيارات التثبيت

يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.

مراجعة ملفات المصدر

اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.

العودة إلى البحث العودة إلى التثبيت

name	braiins-api-mapper
version	1.0.0
category	api-integration
complexity	moderate
status	active
created	2025-12-18T00:00:00.000Z
author	braiins-pool-mcp-server
description	Maps Braiins Pool API endpoints to MCP tool implementations with proper authentication, rate limiting, retry logic, and error handling patterns.
triggers	["map API endpoint","integrate Braiins API","connect to pool endpoint","implement API call","API client method"]
dependencies	["braiins-cache-strategist"]

Braiins API Mapper Skill

Description

Map Braiins Pool API endpoints from API.md to MCP tool implementations. This skill guides the creation of API client methods with proper authentication, retry logic, rate limiting, and error handling following the patterns defined in ARCHITECTURE.md.

When to Use This Skill

When implementing API client methods for new endpoints
When adding authentication to API calls
When designing retry and error handling logic
When mapping response data to MCP tool format
When implementing rate limiting compliance

When NOT to Use This Skill

When designing input schemas (use mcp-schema-designer)
When designing caching strategy (use braiins-cache-strategist)
When implementing the full tool handler (use mcp-tool-builder)

Prerequisites

API.md contains the endpoint specification
ARCHITECTURE.md defines client patterns
HTTP client library available (axios/httpx)
Environment variables configured for API authentication

API Reference

Base Configuration

From API.md Section 2 & 3:

// Environment variables
const BRAIINS_API_BASE_URL = process.env.BRAIINS_API_BASE_URL || 'https://pool.braiins.com/api/v1';
const BRAIINS_API_TOKEN = process.env.BRAIINS_POOL_API_TOKEN;

// Headers for all requests
const headers = {
  'Authorization': `Bearer ${BRAIINS_API_TOKEN}`,
  'Content-Type': 'application/json',
  'Accept': 'application/json',
};

Endpoint Mapping Table

From API.md Sections 5-7:

Endpoint	Method	MCP Tool	Auth	Rate Limit

## Endpoint Analysis: {path}

- **Method**: GET
- **Path**: /workers/{workerId}
- **Path Params**: workerId (string, required)
- **Query Params**: none
- **Auth**: Bearer token required
- **Rate Limit**: 1 request per 60 seconds
- **Response**: WorkerDetails object (see Section 6.2)

// src/api/braiinsClient.ts

interface BraiinsClient {
  // User endpoints
  getUserOverview(): Promise<UserOverviewResponse>;
  getUserRewards(params?: GetUserRewardsParams): Promise<UserRewardsResponse>;

  // Worker endpoints
  listWorkers(params?: ListWorkersParams): Promise<WorkerListResponse>;
  getWorkerDetails(workerId: string): Promise<WorkerDetailsResponse>;
  getWorkerHashrate(workerId: string, params?: TimeRangeParams): Promise<WorkerHashrateResponse>;

  // Pool/Network endpoints
  getPoolStats(): Promise<PoolStatsResponse>;
  getNetworkStats(): Promise<NetworkStatsResponse>;
}

import axios, { AxiosInstance, AxiosError } from 'axios';
import { BraiinsApiError } from '../utils/errors';
import { logger } from '../utils/logger';

class BraiinsClient {
  private client: AxiosInstance;
  private rateLimiter: RateLimiter;

  constructor() {
    this.client = axios.create({
      baseURL: process.env.BRAIINS_API_BASE_URL,
      timeout: 30000, // 30 second timeout
      headers: {
        'Authorization': `Bearer ${process.env.BRAIINS_POOL_API_TOKEN}`,
        'Content-Type': 'application/json',
      },
    });

    this.rateLimiter = new RateLimiter({
      requestsPerSecond: 1,
      burstSize: 5,
    });

    // Add response interceptor for logging
    this.client.interceptors.response.use(
      (response) => {
        logger.debug('API response', {
          path: response.config.url,
          status: response.status,
          duration: response.headers['x-response-time'],
        });
        return response;
      },
      (error) => {
        logger.error('API error', {
          path: error.config?.url,
          status: error.response?.status,
          message: error.message,
        });
        throw error;
      }
    );
  }

  /**
   * Make authenticated request with retry logic
   */
  private async request<T>(
    method: 'GET' | 'POST',
    path: string,
    options?: {
      params?: Record<string, unknown>;
      body?: unknown;
    }
  ): Promise<T> {
    // Wait for rate limiter
    await this.rateLimiter.acquire();

    try {
      const response = await this.retryWithBackoff(async () => {
        return this.client.request<T>({
          method,
          url: path,
          params: options?.params,
          data: options?.body,
        });
      });

      return response.data;
    } catch (error) {
      throw this.transformError(error);
    }
  }

  /**
   * Retry with exponential backoff
   */
  private async retryWithBackoff<T>(
    fn: () => Promise<T>,
    maxRetries = 3,
    baseDelay = 1000
  ): Promise<T> {
    let lastError: Error | undefined;

    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      try {
        return await fn();
      } catch (error) {
        lastError = error as Error;

        // Don't retry client errors (4xx)
        if (error instanceof AxiosError && error.response) {
          const status = error.response.status;
          if (status >= 400 && status < 500) {
            throw error;
          }
        }

        // Wait before retry (exponential backoff)
        if (attempt < maxRetries) {
          const delay = baseDelay * Math.pow(2, attempt);
          logger.warn('Retrying request', { attempt: attempt + 1, delay });
          await this.sleep(delay);
        }
      }
    }

    throw lastError;
  }

  /**
   * Transform axios errors to custom errors
   */
  private transformError(error: unknown): BraiinsApiError {
    if (error instanceof AxiosError && error.response) {
      const status = error.response.status;
      const data = error.response.data;

      // Map HTTP status to error code
      const errorMap: Record<number, string> = {
        400: 'BAD_REQUEST',
        401: 'UNAUTHORIZED',
        403: 'FORBIDDEN',
        404: 'NOT_FOUND',
        429: 'RATE_LIMITED',
        500: 'SERVER_ERROR',
      };

      return new BraiinsApiError(
        data?.message || error.message,
        errorMap[status] || 'UNKNOWN_ERROR',
        status
      );
    }

    return new BraiinsApiError(
      'Network error',
      'NETWORK_ERROR',
      0
    );
  }

  private sleep(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

/**
 * Get user overview statistics
 *
 * @see API.md Section 5.1
 * @returns User hashrate, rewards, and worker counts
 */
async getUserOverview(): Promise<UserOverviewResponse> {
  return this.request<UserOverviewResponse>('GET', '/user/overview');
}

interface ListWorkersParams {
  page?: number;
  pageSize?: number;
  status?: 'active' | 'inactive' | 'all';
  search?: string;
  sortBy?: string;
}

/**
 * List workers with pagination and filtering
 *
 * @see API.md Section 6.1
 * @param params - Pagination and filter options
 * @returns Paginated list of workers
 */
async listWorkers(params?: ListWorkersParams): Promise<WorkerListResponse> {
  return this.request<WorkerListResponse>('GET', '/workers', {
    params: {
      page: params?.page ?? 1,
      page_size: params?.pageSize ?? 50,
      status: params?.status ?? 'all',
      search: params?.search,
      sort_by: params?.sortBy,
    },
  });
}

/**
 * Get detailed information for a specific worker
 *
 * @see API.md Section 6.2
 * @param workerId - Unique worker identifier
 * @returns Worker details including hashrate, status, hardware info
 */
async getWorkerDetails(workerId: string): Promise<WorkerDetailsResponse> {
  // Validate workerId to prevent path traversal
  if (!workerId.match(/^[a-zA-Z0-9\-_]+$/)) {
    throw new BraiinsApiError('Invalid worker ID format', 'VALIDATION_ERROR', 400);
  }

  return this.request<WorkerDetailsResponse>('GET', `/workers/${workerId}`);
}

interface TimeRangeParams {
  from?: string; // ISO 8601
  to?: string;   // ISO 8601
  granularity?: 'minute' | 'hour' | 'day';
}

/**
 * Get hashrate timeseries for a worker
 *
 * @see API.md Section 6.3
 * @param workerId - Unique worker identifier
 * @param params - Time range and granularity options
 * @returns Array of timestamped hashrate values
 */
async getWorkerHashrate(
  workerId: string,
  params?: TimeRangeParams
): Promise<WorkerHashrateResponse> {
  if (!workerId.match(/^[a-zA-Z0-9\-_]+$/)) {
    throw new BraiinsApiError('Invalid worker ID format', 'VALIDATION_ERROR', 400);
  }

  return this.request<WorkerHashrateResponse>('GET', `/workers/${workerId}/hashrate`, {
    params: {
      from: params?.from,
      to: params?.to,
      granularity: params?.granularity ?? 'hour',
    },
  });
}

// tests/unit/api/braiinsClient.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { BraiinsClient } from '../../../src/api/braiinsClient';
import nock from 'nock';

describe('BraiinsClient', () => {
  let client: BraiinsClient;

  beforeEach(() => {
    client = new BraiinsClient();
    nock.cleanAll();
  });

  describe('getUserOverview', () => {
    it('should return user overview on success', async () => {
      const mockResponse = {
        username: 'test_user',
        hashrate: { current: 100000000000000 },
      };

      nock(process.env.BRAIINS_API_BASE_URL!)
        .get('/user/overview')
        .reply(200, mockResponse);

      const result = await client.getUserOverview();
      expect(result).toEqual(mockResponse);
    });

    it('should throw on 401 unauthorized', async () => {
      nock(process.env.BRAIINS_API_BASE_URL!)
        .get('/user/overview')
        .reply(401, { message: 'Invalid token' });

      await expect(client.getUserOverview()).rejects.toThrow('UNAUTHORIZED');
    });
  });

  describe('retry logic', () => {
    it('should retry on 500 errors', async () => {
      let attempts = 0;
      nock(process.env.BRAIINS_API_BASE_URL!)
        .get('/user/overview')
        .times(2)
        .reply(() => {
          attempts++;
          return [500, { message: 'Server error' }];
        })
        .get('/user/overview')
        .reply(200, { username: 'test' });

      const result = await client.getUserOverview();
      expect(attempts).toBe(2);
      expect(result.username).toBe('test');
    });

    it('should not retry on 400 errors', async () => {
      let attempts = 0;
      nock(process.env.BRAIINS_API_BASE_URL!)
        .get('/user/overview')
        .reply(() => {
          attempts++;
          return [400, { message: 'Bad request' }];
        });

      await expect(client.getUserOverview()).rejects.toThrow('BAD_REQUEST');
      expect(attempts).toBe(1);
    });
  });

  describe('path parameter validation', () => {
    it('should reject invalid worker ID', async () => {
      await expect(client.getWorkerDetails('../../../etc/passwd')).rejects.toThrow('VALIDATION_ERROR');
    });

    it('should accept valid worker ID', async () => {
      nock(process.env.BRAIINS_API_BASE_URL!)
        .get('/workers/valid-worker-123')
        .reply(200, { id: 'valid-worker-123' });

      const result = await client.getWorkerDetails('valid-worker-123');
      expect(result.id).toBe('valid-worker-123');
    });
  });
});

HTTP Status	Error Code	Retry?	User Message
400	BAD_REQUEST	No	Invalid request parameters
401	UNAUTHORIZED	No	Authentication failed - check API token
403	FORBIDDEN	No	Permission denied for this operation
404	NOT_FOUND	No	Resource not found
429	RATE_LIMITED	Yes (with delay)	Too many requests - please wait
500	SERVER_ERROR	Yes	Server error - please try again
Network	NETWORK_ERROR	Yes	Network connection failed

GET /user/overview
Auth: Bearer token
Response: UserOverviewResponse

async getUserOverview(): Promise<UserOverviewResponse> {
  return this.request<UserOverviewResponse>('GET', '/user/overview');
}

GET /workers
Auth: Bearer token
Query: page, page_size, status, search, sort_by
Response: WorkerListResponse

async listWorkers(params?: ListWorkersParams): Promise<WorkerListResponse> {
  return this.request<WorkerListResponse>('GET', '/workers', {
    params: {
      page: params?.page ?? 1,
      page_size: params?.pageSize ?? 50,
      status: params?.status,
      search: params?.search,
      sort_by: params?.sortBy,
    },
  });
}

GET /workers/{workerId}
Auth: Bearer token
Path: workerId (string)
Response: WorkerDetailsResponse

async getWorkerDetails(workerId: string): Promise<WorkerDetailsResponse> {
  // Validate to prevent path traversal
  if (!workerId.match(/^[a-zA-Z0-9\-_]+$/)) {
    throw new BraiinsApiError('Invalid worker ID', 'VALIDATION_ERROR', 400);
  }

  return this.request<WorkerDetailsResponse>('GET', `/workers/${workerId}`);
}

// BAD: Path traversal vulnerability
async getWorker(id: string) {
  return this.request('GET', `/workers/${id}`);
}

// GOOD: Validate input
async getWorker(id: string) {
  if (!id.match(/^[a-zA-Z0-9\-_]+$/)) throw new Error('Invalid ID');
  return this.request('GET', `/workers/${id}`);
}

// BAD: Retrying 400/401 errors wastes requests
if (error.status >= 400) retry();

// GOOD: Only retry server errors
if (error.status >= 500) retry();

// BAD: Can't change between environments
const url = 'https://pool.braiins.com/api/v1/users';

// GOOD: Use environment variable
const url = `${process.env.BRAIINS_API_BASE_URL}/users`;