@framers/agentos-ext-domain-porkbun 0.1.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@framers/agentos-ext-domain-porkbun",
+  "version": "0.1.0",
+  "description": "Porkbun domain registrar extension — search, register, and manage domains and DNS records via the Porkbun API v3.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "sideEffects": true,
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./manifest.json": "./manifest.json",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "agentos",
+    "extension",
+    "domain",
+    "porkbun",
+    "registrar",
+    "dns",
+    "nameserver"
+  ],
+  "author": {
+    "name": "Framers AI",
+    "email": "team@frame.dev",
+    "url": "https://frame.dev"
+  },
+  "contributors": [
+    {
+      "name": "Johnny Dunn",
+      "email": "johnnyfived@protonmail.com",
+      "url": "https://github.com/jddunn"
+    }
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/framersai/agentos-extensions.git",
+    "directory": "registry/curated/domains/porkbun"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@framers/agentos": "^0.5.2"
+  },
+  "devDependencies": {
+    "@framers/agentos": "^0.6.6",
+    "@types/node": "^20.12.12",
+    "rimraf": "^5.0.7",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}

package/src/PorkbunService.ts

@@ -0,0 +1,327 @@
+// @ts-nocheck
+/**
+ * @fileoverview Porkbun API v3 service layer.
+ *
+ * Wraps the Porkbun REST API for domain registration, availability checks,
+ * DNS record management, and domain transfers.
+ *
+ * NOTE: Porkbun uses POST for ALL endpoints and requires apikey + secretapikey
+ * in every request body.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PorkbunConfig {
+  /** Porkbun API key (from https://porkbun.com/account/api) */
+  apiKey: string;
+  /** Porkbun secret API key */
+  secretApiKey: string;
+  /** API base URL (defaults to https://api.porkbun.com/api/json/v3) */
+  baseUrl?: string;
+}
+
+export interface DomainAvailability {
+  domain: string;
+  available: boolean;
+  pricing?: DomainPricing;
+}
+
+export interface DomainPricing {
+  registration: string;
+  renewal: string;
+  transfer: string;
+  couponed?: string;
+}
+
+export interface OwnedDomain {
+  domain: string;
+  status: string;
+  tld: string;
+  createDate: string;
+  expireDate: string;
+  securityLock: boolean;
+  whoisPrivacy: boolean;
+  autoRenew: boolean;
+  notLocal: boolean;
+}
+
+export interface DnsRecord {
+  id: string;
+  name: string;
+  type: string;
+  content: string;
+  ttl: string;
+  prio: string | null;
+  notes: string | null;
+}
+
+export interface RegisterDomainOptions {
+  domain: string;
+  years?: number;
+  /** Registrant contact fields (optional — Porkbun uses account defaults) */
+  firstName?: string;
+  lastName?: string;
+  email?: string;
+  phone?: string;
+  city?: string;
+  state?: string;
+  zip?: string;
+  country?: string;
+  organization?: string;
+  address?: string;
+}
+
+export interface RegisterDomainResult {
+  domain: string;
+  status: string;
+  message: string;
+}
+
+export interface DnsRecordInput {
+  name?: string;
+  type: 'A' | 'AAAA' | 'CNAME' | 'TXT' | 'MX' | 'NS' | 'SRV' | 'TLSA' | 'CAA' | 'ALIAS';
+  content: string;
+  ttl?: string;
+  prio?: string;
+}
+
+export interface TransferDomainResult {
+  domain: string;
+  status: string;
+  message: string;
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+export class PorkbunService {
+  private config: PorkbunConfig;
+  private running = false;
+
+  constructor(config: PorkbunConfig) {
+    this.config = {
+      ...config,
+      baseUrl: config.baseUrl ?? 'https://api.porkbun.com/api/json/v3',
+    };
+  }
+
+  async initialize(): Promise<void> {
+    // Validate auth by pinging the API
+    const res = await this.post('/ping', {});
+    if (res.status !== 'SUCCESS') {
+      throw new Error(`Porkbun auth failed: ${res.message ?? JSON.stringify(res)}`);
+    }
+    this.running = true;
+  }
+
+  async shutdown(): Promise<void> {
+    this.running = false;
+  }
+
+  get isRunning(): boolean {
+    return this.running;
+  }
+
+  // ── Domain Availability ─────────────────────────────────────────────────
+
+  /** Check if a domain is available for registration. */
+  async checkAvailability(domain: string): Promise<DomainAvailability> {
+    const res = await this.post('/domain/checkAvailability', { domain });
+    const available = res.avail === true || res.avail === 'true' || res.status === 'SUCCESS';
+
+    let pricing: DomainPricing | undefined;
+    // Also fetch pricing if available
+    try {
+      pricing = await this.getPricing(domain);
+    } catch {
+      // Pricing may fail for unavailable domains — that's okay
+    }
+
+    return {
+      domain,
+      available,
+      pricing,
+    };
+  }
+
+  /** Get pricing information for a domain/TLD. */
+  async getPricing(domain: string): Promise<DomainPricing> {
+    const res = await this.post('/domain/pricing/get', { domain });
+    const p = res.pricing ?? res;
+    return {
+      registration: p.registration ?? p.register ?? '',
+      renewal: p.renewal ?? p.renew ?? '',
+      transfer: p.transfer ?? '',
+      couponed: p.couponed,
+    };
+  }
+
+  // ── Domain Registration ─────────────────────────────────────────────────
+
+  /** Register (purchase) a domain. */
+  async registerDomain(opts: RegisterDomainOptions): Promise<RegisterDomainResult> {
+    const body: Record<string, unknown> = {
+      domain: opts.domain,
+      years: opts.years ?? 1,
+    };
+
+    // Add optional contact fields
+    if (opts.firstName) body.firstName = opts.firstName;
+    if (opts.lastName) body.lastName = opts.lastName;
+    if (opts.email) body.email = opts.email;
+    if (opts.phone) body.phone = opts.phone;
+    if (opts.city) body.city = opts.city;
+    if (opts.state) body.stateProvince = opts.state;
+    if (opts.zip) body.zip = opts.zip;
+    if (opts.country) body.country = opts.country;
+    if (opts.organization) body.organization = opts.organization;
+    if (opts.address) body.addressLine1 = opts.address;
+
+    const res = await this.post('/domain/register', body);
+    return {
+      domain: opts.domain,
+      status: res.status ?? 'UNKNOWN',
+      message: res.message ?? `Domain ${opts.domain} registration ${res.status === 'SUCCESS' ? 'successful' : 'failed'}.`,
+    };
+  }
+
+  // ── Domain Listing ──────────────────────────────────────────────────────
+
+  /** List all domains owned by the account. */
+  async listDomains(): Promise<OwnedDomain[]> {
+    const res = await this.post('/domain/listAll', {});
+    return (res.domains ?? []).map((d: any) => ({
+      domain: d.domain ?? '',
+      status: d.status ?? '',
+      tld: d.tld ?? '',
+      createDate: d.createDate ?? '',
+      expireDate: d.expireDate ?? '',
+      securityLock: d.securityLock === '1' || d.securityLock === true,
+      whoisPrivacy: d.whoisPrivacy === '1' || d.whoisPrivacy === true,
+      autoRenew: d.autoRenew === '1' || d.autoRenew === true,
+      notLocal: d.notLocal === '1' || d.notLocal === true,
+    }));
+  }
+
+  // ── DNS Management ──────────────────────────────────────────────────────
+
+  /** Create a DNS record for a domain. */
+  async createDnsRecord(domain: string, record: DnsRecordInput): Promise<{ id: string }> {
+    const body: Record<string, unknown> = {
+      name: record.name ?? '',
+      type: record.type,
+      content: record.content,
+      ttl: record.ttl ?? '300',
+    };
+    if (record.prio) body.prio = record.prio;
+
+    const res = await this.post(`/dns/create/${domain}`, body);
+    return { id: String(res.id ?? '') };
+  }
+
+  /** Edit an existing DNS record. */
+  async editDnsRecord(domain: string, recordId: string, record: Partial<DnsRecordInput>): Promise<void> {
+    const body: Record<string, unknown> = {};
+    if (record.name !== undefined) body.name = record.name;
+    if (record.type) body.type = record.type;
+    if (record.content) body.content = record.content;
+    if (record.ttl) body.ttl = record.ttl;
+    if (record.prio) body.prio = record.prio;
+
+    await this.post(`/dns/edit/${domain}/${recordId}`, body);
+  }
+
+  /** Delete a DNS record. */
+  async deleteDnsRecord(domain: string, recordId: string): Promise<void> {
+    await this.post(`/dns/delete/${domain}/${recordId}`, {});
+  }
+
+  /** List all DNS records for a domain. */
+  async listDnsRecords(domain: string): Promise<DnsRecord[]> {
+    const res = await this.post(`/dns/retrieve/${domain}`, {});
+    return (res.records ?? []).map((r: any) => this.mapDnsRecord(r));
+  }
+
+  /** Retrieve DNS records by name and type. */
+  async getDnsRecordsByNameType(domain: string, type: string, subdomain?: string): Promise<DnsRecord[]> {
+    const sub = subdomain ?? '';
+    const res = await this.post(`/dns/retrieveByNameType/${domain}/${type}/${sub}`, {});
+    return (res.records ?? []).map((r: any) => this.mapDnsRecord(r));
+  }
+
+  // ── Domain Transfer ─────────────────────────────────────────────────────
+
+  /** Initiate a domain transfer to Porkbun. */
+  async transferDomain(domain: string, authCode: string): Promise<TransferDomainResult> {
+    const res = await this.post('/domain/transfer', {
+      domain,
+      authCode,
+    });
+    return {
+      domain,
+      status: res.status ?? 'UNKNOWN',
+      message: res.message ?? `Domain transfer for ${domain} ${res.status === 'SUCCESS' ? 'initiated' : 'failed'}.`,
+    };
+  }
+
+  // ── Helpers ─────────────────────────────────────────────────────────────
+
+  /**
+   * POST helper — all Porkbun endpoints are POST and require
+   * apikey + secretapikey in the body.
+   */
+  private async post(path: string, body: Record<string, unknown>): Promise<any> {
+    const url = `${this.config.baseUrl}${path}`;
+    const payload = {
+      apikey: this.config.apiKey,
+      secretapikey: this.config.secretApiKey,
+      ...body,
+    };
+
+    const res = await globalThis.fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+
+    return this.handleResponse(res);
+  }
+
+  /** Parse the response JSON, throwing on HTTP errors. */
+  private async handleResponse(res: Response): Promise<any> {
+    const text = await res.text();
+    let data: any;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      throw new Error(`Porkbun API ${res.status}: invalid JSON — ${text.slice(0, 500)}`);
+    }
+
+    if (!res.ok) {
+      throw new Error(
+        `Porkbun API ${res.status}: ${data.message ?? text.slice(0, 500)}`,
+      );
+    }
+
+    if (data.status === 'ERROR') {
+      throw new Error(`Porkbun API error: ${data.message ?? 'unknown error'}`);
+    }
+
+    return data;
+  }
+
+  private mapDnsRecord(r: any): DnsRecord {
+    return {
+      id: String(r.id ?? ''),
+      name: r.name ?? '',
+      type: r.type ?? '',
+      content: r.content ?? '',
+      ttl: String(r.ttl ?? '300'),
+      prio: r.prio ? String(r.prio) : null,
+      notes: r.notes ?? null,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,133 @@
+// @ts-nocheck
+/**
+ * @fileoverview Porkbun Domain Registrar Extension for AgentOS.
+ *
+ * Provides 5 tools for searching, registering, and managing domains and DNS
+ * records via the Porkbun API v3.
+ *
+ * @module @framers/agentos-ext-domain-porkbun
+ */
+
+import { PorkbunService } from './PorkbunService.js';
+import type { PorkbunConfig } from './PorkbunService.js';
+import { PorkbunSearchDomainTool } from './tools/searchDomain.js';
+import { PorkbunRegisterDomainTool } from './tools/registerDomain.js';
+import { PorkbunListDomainsTool } from './tools/listDomains.js';
+import { PorkbunConfigureDnsTool } from './tools/configureDns.js';
+import { PorkbunTransferDomainTool } from './tools/transferDomain.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface PorkbunDomainOptions {
+  apiKey?: string;
+  secretApiKey?: string;
+  secrets?: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Secret Resolution
+// ---------------------------------------------------------------------------
+
+function resolveConfig(opts: PorkbunDomainOptions, secrets: Record<string, string>): PorkbunConfig {
+  return {
+    apiKey:
+      opts.apiKey ?? secrets['porkbun.apiKey']
+      ?? process.env.PORKBUN_API_KEY ?? '',
+    secretApiKey:
+      opts.secretApiKey ?? secrets['porkbun.secretApiKey']
+      ?? process.env.PORKBUN_SECRET_API_KEY ?? '',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Extension Context
+// ---------------------------------------------------------------------------
+
+export interface ExtensionContext {
+  options?: Record<string, unknown>;
+  secrets?: Record<string, string>;
+  getSecret?: (key: string) => string | undefined;
+  logger?: { info: (msg: string) => void };
+}
+
+export interface ExtensionPack {
+  name: string;
+  version: string;
+  descriptors: Array<{ id: string; kind: string; priority?: number; payload: unknown }>;
+  onActivate?: () => Promise<void>;
+  onDeactivate?: () => Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createExtensionPack(context: ExtensionContext): ExtensionPack {
+  const opts = (context.options ?? {}) as PorkbunDomainOptions;
+  const secrets = opts.secrets ?? context.secrets ?? {};
+  const config = resolveConfig(opts, secrets);
+
+  const service = new PorkbunService(config);
+
+  const searchDomainTool = new PorkbunSearchDomainTool(service);
+  const registerDomainTool = new PorkbunRegisterDomainTool(service);
+  const listDomainsTool = new PorkbunListDomainsTool(service);
+  const configureDnsTool = new PorkbunConfigureDnsTool(service);
+  const transferDomainTool = new PorkbunTransferDomainTool(service);
+
+  return {
+    name: '@framers/agentos-ext-domain-porkbun',
+    version: '0.1.0',
+    descriptors: [
+      { id: 'porkbunSearchDomain', kind: 'tool', priority: 40, payload: searchDomainTool },
+      { id: 'porkbunRegisterDomain', kind: 'tool', priority: 40, payload: registerDomainTool },
+      { id: 'porkbunListDomains', kind: 'tool', priority: 40, payload: listDomainsTool },
+      { id: 'porkbunConfigureDns', kind: 'tool', priority: 40, payload: configureDnsTool },
+      { id: 'porkbunTransferDomain', kind: 'tool', priority: 40, payload: transferDomainTool },
+    ],
+    onActivate: async () => {
+      if (!config.apiKey) {
+        throw new Error(
+          'Porkbun: no API key provided. Set PORKBUN_API_KEY environment variable, '
+          + 'or provide it via secrets["porkbun.apiKey"].',
+        );
+      }
+      if (!config.secretApiKey) {
+        throw new Error(
+          'Porkbun: no secret API key provided. Set PORKBUN_SECRET_API_KEY environment variable, '
+          + 'or provide it via secrets["porkbun.secretApiKey"].',
+        );
+      }
+      await service.initialize();
+    },
+    onDeactivate: async () => {
+      await service.shutdown();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { PorkbunService } from './PorkbunService.js';
+export type {
+  PorkbunConfig,
+  DomainAvailability,
+  DomainPricing,
+  OwnedDomain,
+  DnsRecord,
+  DnsRecordInput,
+  RegisterDomainOptions,
+  RegisterDomainResult,
+  TransferDomainResult,
+} from './PorkbunService.js';
+export { PorkbunSearchDomainTool } from './tools/searchDomain.js';
+export { PorkbunRegisterDomainTool } from './tools/registerDomain.js';
+export { PorkbunListDomainsTool } from './tools/listDomains.js';
+export { PorkbunConfigureDnsTool } from './tools/configureDns.js';
+export { PorkbunTransferDomainTool } from './tools/transferDomain.js';
+
+export default createExtensionPack;

package/src/tools/configureDns.ts

@@ -0,0 +1,114 @@
+// @ts-nocheck
+/**
+ * @fileoverview PorkbunConfigureDnsTool — manage DNS records for a Porkbun domain.
+ */
+
+import type { PorkbunService, DnsRecord } from '../PorkbunService.js';
+
+export interface ConfigureDnsInput {
+  domain: string;
+  action?: 'add' | 'remove' | 'list' | 'update';
+  recordId?: string;
+  type?: 'A' | 'AAAA' | 'CNAME' | 'TXT' | 'MX' | 'NS' | 'SRV' | 'TLSA' | 'CAA' | 'ALIAS';
+  name?: string;
+  content?: string;
+  ttl?: string;
+  prio?: string;
+}
+
+export class PorkbunConfigureDnsTool {
+  readonly id = 'porkbunConfigureDns';
+  readonly name = 'porkbunConfigureDns';
+  readonly displayName = 'Configure DNS Records';
+  readonly description = 'Manage DNS records for a domain on Porkbun. Supports adding, removing, listing, and updating records of type A, AAAA, CNAME, TXT, MX, NS, SRV, TLSA, CAA, and ALIAS.';
+  readonly category = 'domain';
+  readonly version = '0.1.0';
+  readonly hasSideEffects = true;
+
+  readonly inputSchema = {
+    type: 'object' as const,
+    properties: {
+      domain: { type: 'string', description: 'The domain name (e.g. "example.com")' },
+      action: { type: 'string', enum: ['add', 'remove', 'list', 'update'], description: 'Action to perform (default: list)' },
+      recordId: { type: 'string', description: 'The DNS record ID (required for remove and update actions)' },
+      type: {
+        type: 'string',
+        enum: ['A', 'AAAA', 'CNAME', 'TXT', 'MX', 'NS', 'SRV', 'TLSA', 'CAA', 'ALIAS'],
+        description: 'DNS record type (required for add action)',
+      },
+      name: { type: 'string', description: 'Subdomain or record name (e.g. "www", "mail"). Empty string or omit for root domain.' },
+      content: { type: 'string', description: 'Record value/content (e.g. IP address, hostname, TXT value)' },
+      ttl: { type: 'string', description: 'Time to live in seconds (default: "300")' },
+      prio: { type: 'string', description: 'Priority (required for MX records, optional for others)' },
+    },
+    required: ['domain'],
+  };
+
+  constructor(private service: PorkbunService) {}
+
+  async execute(args: ConfigureDnsInput): Promise<{
+    success: boolean;
+    data?: DnsRecord[] | DnsRecord | { id: string } | { deleted: boolean };
+    error?: string;
+  }> {
+    try {
+      const action = args.action ?? 'list';
+
+      switch (action) {
+        case 'list': {
+          const records = await this.service.listDnsRecords(args.domain);
+          return { success: true, data: records };
+        }
+
+        case 'add': {
+          if (!args.type) {
+            return { success: false, error: 'Record type is required for the "add" action. Provide one of: A, AAAA, CNAME, TXT, MX, NS, SRV, TLSA, CAA, ALIAS.' };
+          }
+          if (!args.content) {
+            return { success: false, error: 'Record content is required for the "add" action (e.g. IP address, hostname, TXT value).' };
+          }
+
+          const created = await this.service.createDnsRecord(args.domain, {
+            name: args.name,
+            type: args.type,
+            content: args.content,
+            ttl: args.ttl,
+            prio: args.prio,
+          });
+          return { success: true, data: created };
+        }
+
+        case 'remove': {
+          if (!args.recordId) {
+            return { success: false, error: 'Record ID is required for the "remove" action. Use action "list" first to find the record ID.' };
+          }
+          await this.service.deleteDnsRecord(args.domain, args.recordId);
+          return { success: true, data: { deleted: true } };
+        }
+
+        case 'update': {
+          if (!args.recordId) {
+            return { success: false, error: 'Record ID is required for the "update" action. Use action "list" first to find the record ID.' };
+          }
+          await this.service.editDnsRecord(args.domain, args.recordId, {
+            name: args.name,
+            type: args.type,
+            content: args.content,
+            ttl: args.ttl,
+            prio: args.prio,
+          });
+
+          // Return the updated records for the domain so the caller can confirm
+          const records = await this.service.listDnsRecords(args.domain);
+          const updated = records.find(r => r.id === args.recordId);
+          return { success: true, data: updated ?? records };
+        }
+
+        default:
+          return { success: false, error: `Unknown action: "${action}". Use one of: add, remove, list, update.` };
+      }
+    } catch (err: any) {
+      return { success: false, error: err.message };
+    }
+  }
+}

package/src/tools/listDomains.ts

@@ -0,0 +1,33 @@
+// @ts-nocheck
+/**
+ * @fileoverview PorkbunListDomainsTool — list all domains owned by the Porkbun account.
+ */
+
+import type { PorkbunService, OwnedDomain } from '../PorkbunService.js';
+
+export class PorkbunListDomainsTool {
+  readonly id = 'porkbunListDomains';
+  readonly name = 'porkbunListDomains';
+  readonly displayName = 'List Owned Domains';
+  readonly description = 'List all domains owned by the connected Porkbun account. Shows domain name, status, TLD, creation and expiry dates, security lock, WHOIS privacy, and auto-renew settings.';
+  readonly category = 'domain';
+  readonly version = '0.1.0';
+  readonly hasSideEffects = false;
+
+  readonly inputSchema = {
+    type: 'object' as const,
+    properties: {},
+    required: [] as string[],
+  };
+
+  constructor(private service: PorkbunService) {}
+
+  async execute(_args: Record<string, never>): Promise<{ success: boolean; data?: OwnedDomain[]; error?: string }> {
+    try {
+      const domains = await this.service.listDomains();
+      return { success: true, data: domains };
+    } catch (err: any) {
+      return { success: false, error: err.message };
+    }
+  }
+}