porkbun-sdk 1.0.0

package/README.md

@@ -0,0 +1,141 @@
+# Porkbun SDK
+
+TypeScript SDK for the [Porkbun](https://porkbun.com) API v3 — manage domains, DNS, SSL and more programmatically.
+
+## Installation
+
+```bash
+npm install porkbun-sdk
+```
+
+## Authentication
+
+The SDK requires API keys from [porkbun.com/account/api](https://porkbun.com/account/api).
+
+```typescript
+import { PorkbunClient } from "porkbun-sdk";
+
+const client = new PorkbunClient({
+  apikey: "pk1_xxxxx",
+  secretapikey: "sk1_xxxxx",
+});
+```
+
+### Via environment variables
+
+```bash
+export PORKBUN_API_KEY=pk1_xxxxx
+export PORKBUN_API_SECRET=sk1_xxxxx
+```
+
+```typescript
+const client = new PorkbunClient({
+  apikey: process.env.PORKBUN_API_KEY!,
+  secretapikey: process.env.PORKBUN_API_SECRET!,
+});
+```
+
+## Usage
+
+```typescript
+import { PorkbunClient } from "porkbun-sdk";
+
+const client = new PorkbunClient({
+  apikey: process.env.PORKBUN_API_KEY!,
+  secretapikey: process.env.PORKBUN_API_SECRET!,
+});
+
+// Ping (test credentials)
+const ping = await client.ping();
+console.log(ping.yourIp);
+
+// Pricing
+const pricing = await client.pricing.get();
+
+// Domains
+const domains = await client.domain.listAll();
+const check = await client.domain.check("example.com");
+const ns = await client.domain.getNameServers("example.com");
+await client.domain.updateNameServers("example.com", ["ns1.dns.com", "ns2.dns.com"]);
+await client.domain.updateAutoRenew({ status: "on" }, "example.com");
+
+// URL Forwarding
+const forwards = await client.domain.getUrlForwarding("example.com");
+await client.domain.addUrlForward("example.com", {
+  location: "https://target.com",
+  type: "permanent",
+  includePath: "no",
+  wildcard: "no",
+});
+
+// DNS
+const records = await client.dns.retrieve("example.com");
+const aRecords = await client.dns.retrieveByNameType("example.com", "A", "www");
+const created = await client.dns.create("example.com", {
+  type: "A",
+  content: "1.2.3.4",
+  name: "www",
+  ttl: 600,
+});
+await client.dns.edit("example.com", "12345", {
+  type: "A",
+  content: "5.6.7.8",
+});
+await client.dns.delete("example.com", "12345");
+
+// DNSSEC
+const dnssecRecords = await client.dnssec.get("example.com");
+await client.dnssec.create("example.com", {
+  keyTag: "12345",
+  alg: "13",
+  digestType: "2",
+  digest: "abc123",
+});
+
+// SSL
+const ssl = await client.ssl.retrieve("example.com");
+console.log(ssl.certificatechain);
+```
+
+## Available resources
+
+| Resource | Access | Description |
+|----------|--------|-------------|
+| Pricing | `client.pricing` | Get domain pricing for all TLDs |
+| Domains | `client.domain` | List, check, register, nameservers, auto-renew |
+| URL Forwards | `client.domain` | Add, list, delete URL forwards |
+| Glue Records | `client.domain` | Create, update, delete glue records |
+| DNS | `client.dns` | CRUD DNS records, filter by type/subdomain |
+| DNSSEC | `client.dnssec` | Create, list, delete DS records |
+| SSL | `client.ssl` | Retrieve certificate bundles |
+
+## Error handling
+
+```typescript
+import { PorkbunClient, PorkbunError } from "porkbun-sdk";
+
+try {
+  const records = await client.dns.retrieve("example.com");
+} catch (error) {
+  if (error instanceof PorkbunError) {
+    console.error(`Error ${error.status}: ${error.message}`);
+    console.error(`Endpoint: ${error.endpoint}`);
+  }
+}
+```
+
+## Options
+
+```typescript
+const client = new PorkbunClient({
+  apikey: "pk1_xxxxx",
+  secretapikey: "sk1_xxxxx",
+  baseURL: "https://api-ipv4.porkbun.com/api/json/v3",  // IPv4-only endpoint
+  retry: 3,         // Number of retries (default: 2)
+  retryDelay: 1000, // Delay between retries in ms (default: 500)
+});
+```
+
+## License
+
+MIT — yabbal

package/dist/index.d.ts

@@ -0,0 +1,283 @@
+type FetchFn = <T = unknown>(path: string, options?: {
+    method?: string;
+    body?: Record<string, unknown>;
+}) => Promise<T>;
+
+interface PorkbunCredentials {
+    apikey: string;
+    secretapikey: string;
+}
+interface PingResponse {
+    status: string;
+    yourIp: string;
+}
+interface TldPricing {
+    registration: string;
+    renewal: string;
+    transfer: string;
+    coupons?: {
+        registration?: {
+            code: string;
+            amount: number;
+            type: string;
+        };
+    };
+}
+interface PricingResponse {
+    status: string;
+    pricing: Record<string, TldPricing>;
+}
+interface Domain {
+    domain: string;
+    status: string;
+    tld: string;
+    createDate: string;
+    expireDate: string;
+    securityLock: string;
+    whoisPrivacy: string;
+    autoRenew: number;
+    notLocal: number;
+    labels?: DomainLabel[];
+}
+interface DomainLabel {
+    id: string;
+    title: string;
+}
+interface DomainListResponse {
+    status: string;
+    domains: Domain[];
+}
+interface DomainCheckResponse {
+    status: string;
+    response: {
+        avail: string;
+        type?: string;
+        pricing?: {
+            registration?: string;
+            renewal?: string;
+            transfer?: string;
+        };
+        premium?: boolean;
+        yourIp?: string;
+    };
+    limits?: {
+        ttl: number;
+        limit: number;
+        used: number;
+    };
+}
+interface DomainCreateParams {
+    cost: number;
+    agreeToTerms: string;
+}
+interface DomainCreateResponse {
+    status: string;
+    domain: string;
+    cost: number;
+    orderId: number;
+    balance: number;
+    limits?: {
+        ttl: number;
+        limit: number;
+        used: number;
+    };
+}
+interface AutoRenewUpdateParams {
+    status: "on" | "off";
+    domains?: string[];
+}
+interface AutoRenewUpdateResponse {
+    status: string;
+    results?: Record<string, {
+        status: string;
+        message?: string;
+    }>;
+}
+interface NameServersResponse {
+    status: string;
+    ns: string[];
+}
+interface UrlForward {
+    id: string;
+    subdomain: string;
+    location: string;
+    type: string;
+    includePath: string;
+    wildcard: string;
+}
+interface UrlForwardCreateParams {
+    subdomain?: string;
+    location: string;
+    type: "temporary" | "permanent";
+    includePath: "yes" | "no";
+    wildcard: "yes" | "no";
+}
+interface UrlForwardingResponse {
+    status: string;
+    forwards: UrlForward[];
+}
+interface GlueRecord {
+    hostname: string;
+    ips: string[];
+}
+interface GlueRecordsResponse {
+    status: string;
+    hosts: GlueRecord[];
+}
+type DnsRecordType = "A" | "MX" | "CNAME" | "ALIAS" | "TXT" | "NS" | "AAAA" | "SRV" | "TLSA" | "CAA" | "HTTPS" | "SVCB" | "SSHFP";
+interface DnsRecord {
+    id: string;
+    name: string;
+    type: DnsRecordType;
+    content: string;
+    ttl: string;
+    prio: string | null;
+    notes: string | null;
+}
+interface DnsCreateParams {
+    name?: string;
+    type: DnsRecordType;
+    content: string;
+    ttl?: number;
+    prio?: number;
+    notes?: string;
+}
+interface DnsEditParams {
+    name?: string;
+    type: DnsRecordType;
+    content: string;
+    ttl?: number;
+    prio?: number;
+    notes?: string | null;
+}
+interface DnsCreateResponse {
+    status: string;
+    id: string;
+}
+interface DnsRetrieveResponse {
+    status: string;
+    records: DnsRecord[];
+}
+interface DnssecRecord {
+    keyTag: string;
+    alg: string;
+    digestType: string;
+    digest: string;
+}
+interface DnssecCreateParams {
+    keyTag: string;
+    alg: string;
+    digestType: string;
+    digest: string;
+    maxSigLife?: number;
+    keyDataFlags?: number;
+    keyDataProtocol?: number;
+    keyDataAlgo?: number;
+    keyDataPubKey?: string;
+}
+interface DnssecRecordsResponse {
+    status: string;
+    records: Record<string, DnssecRecord>;
+}
+interface SslBundle {
+    status: string;
+    certificatechain: string;
+    privatekey: string;
+    publickey: string;
+}
+interface StatusResponse {
+    status: string;
+    message?: string;
+}
+
+declare class Resource {
+    protected fetch: FetchFn;
+    protected credentials: PorkbunCredentials;
+    constructor(fetch: FetchFn, credentials: PorkbunCredentials);
+    protected authBody(extra?: object): Record<string, unknown>;
+}
+
+declare class DnsResource extends Resource {
+    create(domain: string, params: DnsCreateParams): Promise<DnsCreateResponse>;
+    edit(domain: string, id: string, params: DnsEditParams): Promise<StatusResponse>;
+    editByNameType(domain: string, type: string, subdomain?: string, params?: {
+        content: string;
+        ttl?: number;
+        prio?: number;
+        notes?: string;
+    }): Promise<StatusResponse>;
+    delete(domain: string, id: string): Promise<StatusResponse>;
+    deleteByNameType(domain: string, type: string, subdomain?: string): Promise<StatusResponse>;
+    retrieve(domain: string, id?: string): Promise<DnsRecord[]>;
+    retrieveByNameType(domain: string, type: string, subdomain?: string): Promise<DnsRecord[]>;
+}
+
+declare class DnssecResource extends Resource {
+    create(domain: string, params: DnssecCreateParams): Promise<StatusResponse>;
+    get(domain: string): Promise<Record<string, DnssecRecord>>;
+    delete(domain: string, keyTag: string): Promise<StatusResponse>;
+}
+
+declare class DomainResource extends Resource {
+    listAll(params?: {
+        start?: number;
+        includeLabels?: boolean;
+    }): Promise<DomainListResponse>;
+    check(domain: string): Promise<DomainCheckResponse>;
+    create(domain: string, params: DomainCreateParams): Promise<DomainCreateResponse>;
+    getNameServers(domain: string): Promise<NameServersResponse>;
+    updateNameServers(domain: string, ns: string[]): Promise<StatusResponse>;
+    updateAutoRenew(params: AutoRenewUpdateParams, domain?: string): Promise<AutoRenewUpdateResponse>;
+    getUrlForwarding(domain: string): Promise<UrlForward[]>;
+    addUrlForward(domain: string, params: UrlForwardCreateParams): Promise<StatusResponse>;
+    deleteUrlForward(domain: string, recordId: string): Promise<StatusResponse>;
+    getGlueRecords(domain: string): Promise<GlueRecordsResponse>;
+    createGlueRecord(domain: string, subdomain: string, ips: string[]): Promise<StatusResponse>;
+    updateGlueRecord(domain: string, subdomain: string, ips: string[]): Promise<StatusResponse>;
+    deleteGlueRecord(domain: string, subdomain: string): Promise<StatusResponse>;
+}
+
+declare class PricingResource {
+    private fetch;
+    constructor(fetch: FetchFn);
+    get(): Promise<PricingResponse>;
+}
+
+declare class SslResource extends Resource {
+    retrieve(domain: string): Promise<SslBundle>;
+}
+
+interface PorkbunClientOptions {
+    apikey: string;
+    secretapikey: string;
+    baseURL?: string;
+    retry?: number;
+    retryDelay?: number;
+}
+declare class PorkbunClient {
+    readonly fetch: FetchFn;
+    private readonly credentials;
+    readonly pricing: PricingResource;
+    readonly domain: DomainResource;
+    readonly dns: DnsResource;
+    readonly dnssec: DnssecResource;
+    readonly ssl: SslResource;
+    constructor(options: PorkbunClientOptions);
+    ping(): Promise<PingResponse>;
+}
+
+declare class PorkbunError extends Error {
+    status: number;
+    endpoint: string;
+    details?: unknown | undefined;
+    constructor(message: string, status: number, endpoint: string, details?: unknown | undefined);
+    toJSON(): {
+        error: string;
+        message: string;
+        status: number;
+        endpoint: string;
+        details: unknown;
+    };
+}
+
+export { type AutoRenewUpdateParams, type AutoRenewUpdateResponse, type DnsCreateParams, type DnsCreateResponse, type DnsEditParams, type DnsRecord, type DnsRecordType, type DnsRetrieveResponse, type DnssecCreateParams, type DnssecRecord, type DnssecRecordsResponse, type Domain, type DomainCheckResponse, type DomainCreateParams, type DomainCreateResponse, type DomainLabel, type DomainListResponse, type GlueRecord, type GlueRecordsResponse, type NameServersResponse, type PingResponse, PorkbunClient, type PorkbunClientOptions, type PorkbunCredentials, PorkbunError, type PricingResponse, type SslBundle, type StatusResponse, type TldPricing, type UrlForward, type UrlForwardCreateParams, type UrlForwardingResponse };

package/dist/index.js

@@ -0,0 +1,2 @@
+var c=class extends Error{constructor(t,s,i,a){super(t);this.status=s;this.endpoint=i;this.details=a;this.name="PorkbunError";}toJSON(){return {error:this.name,message:this.message,status:this.status,endpoint:this.endpoint,details:this.details}}};var D=r=>new Promise(e=>setTimeout(e,r)),P=r=>{let{baseURL:e,retry:t=2,retryDelay:s=500,retryStatusCodes:i=[408,429,500,502,503,504]}=r;return async(a,R)=>{let w=`${e}/${a}`,$=R?.method??"POST",S=R?.body?JSON.stringify(R.body):void 0,g;for(let d=0;d<=t;d++){d>0&&await D(s*d);try{let n=await fetch(w,{method:$,headers:{"Content-Type":"application/json"},body:S}),u=await n.json();if(!n.ok||u.status&&u.status!=="SUCCESS"){let b=u.message??n.statusText;if(d<t&&i.includes(n.status)){g=new c(b,n.status,a,u);continue}throw new c(b,n.status,a,u)}return u}catch(n){if(n instanceof c)throw n;if(g=n,d===t)break}}throw g??new c("Request failed",0,a)}};var o=class{constructor(e,t){this.fetch=e;this.credentials=t;}authBody(e){return {...this.credentials,...e}}};var p=class extends o{async create(e,t){return this.fetch(`dns/create/${e}`,{body:this.authBody(t)})}async edit(e,t,s){return this.fetch(`dns/edit/${e}/${t}`,{body:this.authBody(s)})}async editByNameType(e,t,s,i){let a=s?`dns/editByNameType/${e}/${t}/${s}`:`dns/editByNameType/${e}/${t}`;return this.fetch(a,{body:this.authBody(i)})}async delete(e,t){return this.fetch(`dns/delete/${e}/${t}`,{body:this.authBody()})}async deleteByNameType(e,t,s){let i=s?`dns/deleteByNameType/${e}/${t}/${s}`:`dns/deleteByNameType/${e}/${t}`;return this.fetch(i,{body:this.authBody()})}async retrieve(e,t){let s=t?`dns/retrieve/${e}/${t}`:`dns/retrieve/${e}`;return (await this.fetch(s,{body:this.authBody()})).records??[]}async retrieveByNameType(e,t,s){let i=s?`dns/retrieveByNameType/${e}/${t}/${s}`:`dns/retrieveByNameType/${e}/${t}`;return (await this.fetch(i,{body:this.authBody()})).records??[]}};var h=class extends o{async create(e,t){return this.fetch(`dns/createDnssecRecord/${e}`,{body:this.authBody(t)})}async get(e){return (await this.fetch(`dns/getDnssecRecords/${e}`,{body:this.authBody()})).records??{}}async delete(e,t){return this.fetch(`dns/deleteDnssecRecord/${e}/${t}`,{body:this.authBody()})}};var y=class extends o{async listAll(e){return this.fetch("domain/listAll",{body:this.authBody({...e?.start!==void 0&&{start:e.start},...e?.includeLabels&&{includeLabels:"yes"}})})}async check(e){return this.fetch(`domain/checkDomain/${e}`,{body:this.authBody()})}async create(e,t){return this.fetch(`domain/create/${e}`,{body:this.authBody(t)})}async getNameServers(e){return this.fetch(`domain/getNs/${e}`,{body:this.authBody()})}async updateNameServers(e,t){return this.fetch(`domain/updateNs/${e}`,{body:this.authBody({ns:t})})}async updateAutoRenew(e,t){let s=t?`domain/updateAutoRenew/${t}`:"domain/updateAutoRenew";return this.fetch(s,{body:this.authBody({status:e.status,...e.domains&&{domains:e.domains}})})}async getUrlForwarding(e){return (await this.fetch(`domain/getUrlForwarding/${e}`,{body:this.authBody()})).forwards??[]}async addUrlForward(e,t){return this.fetch(`domain/addUrlForward/${e}`,{body:this.authBody(t)})}async deleteUrlForward(e,t){return this.fetch(`domain/deleteUrlForward/${e}/${t}`,{body:this.authBody()})}async getGlueRecords(e){return this.fetch(`domain/getGlue/${e}`,{body:this.authBody()})}async createGlueRecord(e,t,s){return this.fetch(`domain/createGlue/${e}/${t}`,{body:this.authBody({ips:s})})}async updateGlueRecord(e,t,s){return this.fetch(`domain/updateGlue/${e}/${t}`,{body:this.authBody({ips:s})})}async deleteGlueRecord(e,t){return this.fetch(`domain/deleteGlue/${e}/${t}`,{body:this.authBody()})}};var m=class{constructor(e){this.fetch=e;}async get(){return this.fetch("pricing/get")}};var l=class extends o{async retrieve(e){return this.fetch(`ssl/retrieve/${e}`,{body:this.authBody()})}};var f=class{fetch;credentials;pricing;domain;dns;dnssec;ssl;constructor(e){this.credentials={apikey:e.apikey,secretapikey:e.secretapikey},this.fetch=P({baseURL:e.baseURL??"https://api.porkbun.com/api/json/v3",retry:e.retry??2,retryDelay:e.retryDelay??500,retryStatusCodes:[408,429,500,502,503,504]}),this.pricing=new m(this.fetch),this.domain=new y(this.fetch,this.credentials),this.dns=new p(this.fetch,this.credentials),this.dnssec=new h(this.fetch,this.credentials),this.ssl=new l(this.fetch,this.credentials);}async ping(){return this.fetch("ping",{body:{...this.credentials}})}};
+export{f as PorkbunClient,c as PorkbunError};

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "porkbun-sdk",
+	"version": "1.0.0",
+	"description": "TypeScript SDK for the Porkbun API — manage domains, DNS, SSL and more",
+	"type": "module",
+	"license": "MIT",
+	"author": "yabbal",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/yabbal/porkbun.git",
+		"directory": "packages/porkbun-sdk"
+	},
+	"homepage": "https://github.com/yabbal/porkbun",
+	"bugs": {
+		"url": "https://github.com/yabbal/porkbun/issues"
+	},
+	"keywords": [
+		"porkbun",
+		"sdk",
+		"api",
+		"domain",
+		"dns",
+		"ssl",
+		"registrar",
+		"typescript"
+	],
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": ["dist"],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check src/",
+		"format": "biome format --write src/"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.0.6",
+		"tsup": "^8.5.0",
+		"typescript": "^5.8.3"
+	}
+}