Porkbun (v3) API Client

A modern, typed TypeScript client for the Porkbun v3 API.

Built with axios for requests and tested with Bun.

Features

• Fully Typed: Complete TypeScript definitions for all API endpoints and models.
• Modern: Built with axios and modern async/await syntax.
• Organized: API endpoints are grouped into logical clients (dns, domain, ssl, etc.).
• Error Handling: Throws custom PorkbunApiError for API-level failures.

Installation

bun add porkbun-api-client

Or with npm/yarn:

npm install porkbun-api-client
yarn add porkbun-api-client

Basic Usage

Initialize the client with your API and Secret API keys. It's recommended to load these from environment variables.

import { PorkbunApiClient } from 'porkbun-api-client';

const client = new PorkbunApiClient({
    apiKey: process.env.PORKBUN_API_KEY!,
    secretApiKey: process.env.PORKBUN_SECRET_API_KEY!,
});

async function checkIp() {
    try {
        // Ping the API
        const { yourIp } = await client.health.ping();
        console.log(`Porkbun sees my IP as: ${yourIp}`);
    } catch (error) {
        console.error('Failed to ping API:', error);
    }
}

checkIp();

API Reference

API endpoints are grouped by functionality.

Health Check (client.health)

Ping the API

Checks credentials and gets your IP address.

const { yourIp } = await client.health.ping();
console.log(`My IP is: ${yourIp}`);

DNS Management (client.dns)

Retrieve DNS Records

Retrieves all DNS records for a domain.

const { records } = await client.dns.retrieve({ domain: 'example.com' });
console.log(records);

Create a DNS Record

Creates a new DNS record.

const { id } = await client.dns.create({
    domain: 'example.com',
    name: 'www',
    type: 'A',
    content: '1.2.3.4',
    ttl: '300',
});
console.log(`Created record with ID: ${id}`);

Domain Management (client.domain)

List All Domains

Retrieves a list of all domains in your account.

const { domains } = await client.domain.listAll();
console.log(domains);

Error Handling

If the Porkbun API returns an error (e.g., "Invalid API Key" or "Domain not found"), the client will throw a PorkbunApiError.

import { PorkbunApiClient, PorkbunApiError } from 'porkbun-api-client';

const client = new PorkbunApiClient({ apiKey: 'bad', secretApiKey: 'key' });

try {
    await client.health.ping();
} catch (error) {
    if (error instanceof PorkbunApiError) {
        // Error came from the Porkbun API
        console.error(`API Error: ${error.message}`);
    } else {
        // Network error or other issue
        console.error(`HTTP/Network Error: ${error.message}`);
    }
}

Development

This project uses Bun for development and testing.

1. Install dependencies:

   bun install

2. Run tests:

   bun test

Contributing

Contributions are welcome! Please read the contributing guidelines to get started.

Also, please be sure to review our code of conduct.

License

This project is licensed under the MIT License. See the LICENSE file for details.