Class Ptero

Example

Basic Usage

import { Ptero, PteroClient, PteroApp } from "ptero-wrapper";

// Client is needed to access Pterodactyl API client endpoints such as 2fa, account details, etc.
// App is needed to access Pterodactyl API app endpoints such as servers, nodes, etc.
const client = new PteroClient(process.env.BASE_URL, process.env.PTERO_CLIENT_KEY);
const app = new PteroApp(process.env.BASE_URL, process.env.PTERO_APP_KEY);

// Ptero is the main class that combines both client and app.
// It provides methods to access both client and app endpoints in a single instance.
const ptero = new Ptero(client, app);

main();

async function main() {
    const account = await ptero.accounts.getAccount();
    console.log(account);
}
Copy

Example

Rate Limiting Configuration

import { Ptero, PteroClient, PteroApp } from "ptero-wrapper";

// Configure rate limiting options
const client = new PteroClient(
  process.env.BASE_URL, 
  process.env.PTERO_CLIENT_KEY,
  {
    enableAutoRetry: true,  // Automatically retry on 429 errors (default: true)
    maxRetries: 5,          // Maximum retry attempts (default: 3)
    baseDelay: 2000         // Base delay for exponential backoff in ms (default: 1000)
  }
);

const app = new PteroApp(
  process.env.BASE_URL, 
  process.env.PTERO_APP_KEY,
  {
    enableAutoRetry: true,
    maxRetries: 3,
    baseDelay: 1500
  }
);

const ptero = new Ptero(client, app);
Copy

Example

Monitoring Rate Limits

import { Ptero, PteroClient, PteroApp } from "ptero-wrapper";

const client = new PteroClient(process.env.BASE_URL, process.env.PTERO_CLIENT_KEY);
const app = new PteroApp(process.env.BASE_URL, process.env.PTERO_APP_KEY);
const ptero = new Ptero(client, app);

async function monitorRateLimits() {
  // Check current rate limit status
  const clientRateLimit = ptero.getClientRateLimit();
  const appRateLimit = ptero.getAppRateLimit();

  if (clientRateLimit) {
    console.log(`Client API: ${clientRateLimit.remaining}/${clientRateLimit.limit} requests remaining`);
    console.log(`Client API resets at: ${clientRateLimit.resetDate}`);
  }

  if (appRateLimit) {
    console.log(`App API: ${appRateLimit.remaining}/${appRateLimit.limit} requests remaining`);
    console.log(`App API resets at: ${appRateLimit.resetDate}`);
  }

  // Check if approaching limits
  if (ptero.isClientApproachingRateLimit()) {
    console.warn("Warning: Client API is approaching rate limit!");
  }

  if (ptero.isAppApproachingRateLimit()) {
    console.warn("Warning: Application API is approaching rate limit!");
  }

  // Make API calls - rate limiting is handled automatically
  try {
    const servers = await ptero.servers.getAllServers();
    console.log(`Found ${servers.data.length} servers`);
  } catch (error) {
    console.error("API call failed:", error);
  }
}

// Monitor rate limits every 30 seconds
setInterval(monitorRateLimits, 30000);
Copy

Example

Advanced Rate Limit Handling

import { Ptero, PteroClient, PteroApp, RateLimitInfo } from "ptero-wrapper";

const client = new PteroClient(process.env.BASE_URL, process.env.PTERO_CLIENT_KEY);
const ptero = new Ptero(client);

async function smartAPICall() {
  // Check rate limit before making expensive operations
  const rateLimit = ptero.getClientRateLimit();
  
  if (rateLimit && rateLimit.remaining < 10) {
    const timeUntilReset = rateLimit.resetDate.getTime() - Date.now();
    console.log(`Low on API calls (${rateLimit.remaining} remaining)`);
    console.log(`Waiting ${Math.ceil(timeUntilReset / 1000)}s until reset...`);
    
    // Wait until rate limit resets
    await new Promise(resolve => setTimeout(resolve, timeUntilReset + 1000));
  }

  // Now make the API call
  const account = await ptero.accounts.getAccount();
  return account;
}
Copy

Rate Limiting Features

• Automatic tracking: Rate limit information is automatically extracted from API response headers
• Smart delays: The library automatically delays requests when approaching rate limits
• Exponential backoff: When rate limits are exceeded (429 errors), requests are retried with exponential backoff
• Separate tracking: Client API and Application API rate limits are tracked separately
• Configurable: Retry behavior, delays, and maximum attempts can be customized
• Monitoring: Current rate limit status and remaining requests are easily accessible

Rate Limit Information

Pterodactyl API implements the following rate limits:

• Client API: 240 requests per minute per API key
• Application API: 240 requests per minute per API key

Rate limit headers returned by the API:

• X-RateLimit-Limit: Maximum requests per minute (240)
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Unix timestamp when the rate limit resets