@elasticapi/wpengine-typescript-sdk

WP Engine TypeScript SDK (Unofficial)

An unofficial TypeScript SDK for interacting with the WP Engine API. This SDK provides a simple and type-safe way to interact with WP Engine's services from both Node.js and browser environments.

Note: This is an unofficial SDK maintained by Jeremy Pollock ([e-mail]) and is not affiliated with or supported by WP Engine.

Features

• Full TypeScript support with complete type definitions
• Environment-based configuration
• Support for all WP Engine API endpoints
• Built-in authentication handling
• Comprehensive input validation
• Client-side rate limiting
• Secure error handling
• Example implementations
• Unit and functional tests
• Support for both CommonJS and ES Modules

Installation

npm install @elasticapi/wpengine-typescript-sdk

Usage

There are several ways to initialize the SDK:

1. Direct Credentials with Rate Limiting

import { WPEngineSDK } from '@elasticapi/wpengine-typescript-sdk';

const sdk = new WPEngineSDK({
  username: 'your-api-username',
  password: 'your-api-password'
}, undefined, 'Default', {
  maxRequestsPerSecond: 5  // Optional: Default is 5
});

2. Environment Variables

Create a .env file:

WPENGINE_USERNAME=your-api-username
WPENGINE_PASSWORD=your-api-password

Then initialize:

const sdk = new WPEngineSDK();

3. Configuration File

Create a configuration file (e.g., config.ini):

[Default]
WPENGINE_USERNAME=your-api-username
WPENGINE_PASSWORD=your-api-password

[Production]
WPENGINE_USERNAME=prod-api-username
WPENGINE_PASSWORD=prod-api-password

Then initialize with a specific profile:

const sdk = new WPEngineSDK(undefined, './config.ini', 'Production');

Rate Limiting

The SDK includes built-in rate limiting to prevent API throttling:

import { WPEngineSDK, RateLimitError } from '@elasticapi/wpengine-typescript-sdk';

// Initialize with custom rate limit
const sdk = new WPEngineSDK(credentials, undefined, 'Default', {
  maxRequestsPerSecond: 5  // Limit to 5 requests per second
});

// Handle rate limit errors
try {
  await sdk.accounts.listAccounts();
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Rate limit exceeded, waiting...');
  }
}

// Check rate limiter status
const stats = sdk.getRateLimiterStats();
console.log('Available requests:', stats.availableTokens);
console.log('Wait time (ms):', stats.waitTime);

The rate limiter uses a token bucket algorithm to:

• Allow burst traffic up to the limit
• Smoothly handle sustained traffic
• Automatically queue requests when limit is reached
• Provide visibility into rate limit status

Input Validation

The SDK includes comprehensive input validation to prevent errors and improve security:

import { WPEngineSDK, ValidationError } from '@elasticapi/wpengine-typescript-sdk';

try {
  await sdk.accountUsers.createAccountUser('account-id', {
    user: {
      first_name: 'John',
      last_name: 'Doe',
      email: '[e-mail]',
      roles: 'full'
    }
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Validation failed:', error.message);
  }
}

See Validation Documentation for detailed information about the validation system.

Security Best Practices

1. Rate Limiting

   • Use appropriate rate limits for your use case
   • Handle rate limit errors gracefully
   • Monitor rate limit statistics

2. Credential Storage

   • Never commit credentials to version control
   • Use environment variables in production environments
   • Ensure configuration files have appropriate permissions (0600)

3. Input Validation

   • Always handle validation errors appropriately
   • Validate user input before making API calls
   • Use TypeScript types for additional type safety

API Usage Examples

User Management

// List users in an account
const users = await sdk.accountUsers.listAccountUsers('account-id');

// Add a user to an account
await sdk.accountUsers.createAccountUser('account-id', {
  user: {
    account_id: 'account-id',
    first_name: 'John',
    last_name: 'Doe',
    email: '[e-mail]',
    roles: 'full'
  }
});

// Remove a user from an account
await sdk.accountUsers.deleteAccountUser('account-id', 'user-id');

Site Management

// List sites
const sites = await sdk.sites.listSites();

// Get site details
const site = await sdk.sites.getSite('site-id');

Backup Management

// List backups
const backups = await sdk.backups.listBackups('install-id');

// Create a backup
await sdk.backups.createBackup('install-id', {
  backup: {
    description: 'Pre-deployment backup'
  }
});

Error Handling

The SDK uses standard Promise-based error handling with additional error types:

try {
  const users = await sdk.accountUsers.listAccountUsers('account-id');
} catch (error) {
  if (error instanceof ValidationError) {
    // Handle validation error
    console.error('Validation Error:', error.message);
  } else if (error instanceof RateLimitError) {
    // Handle rate limit error
    console.error('Rate Limit Error:', error.message);
  } else if (error.response) {
    // API error response
    console.error('API Error:', error.response.data);
  } else if (error.request) {
    // Network error
    console.error('Network Error:', error.message);
  } else {
    // Other error
    console.error('Error:', error.message);
  }
}

Development

Building

npm run build

Testing

npm test

Running Examples

npm run example:user
npm run example:site
npm run example:backup
npm run example:validation
npm run example:rate-limit

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

Maintainer

This SDK is maintained by Jeremy Pollock ([e-mail]). For any questions, issues, or contributions, please reach out directly.