@framers/agentos-ext-domain-porkbun 0.1.0

package/src/tools/registerDomain.ts

@@ -0,0 +1,74 @@
+// @ts-nocheck
+/**
+ * @fileoverview PorkbunRegisterDomainTool — register (purchase) a domain through Porkbun.
+ */
+
+import type { PorkbunService, RegisterDomainResult } from '../PorkbunService.js';
+
+export interface RegisterDomainInput {
+  domain: string;
+  years?: number;
+  firstName?: string;
+  lastName?: string;
+  email?: string;
+  phone?: string;
+  city?: string;
+  state?: string;
+  zip?: string;
+  country?: string;
+  organization?: string;
+  address?: string;
+}
+
+export class PorkbunRegisterDomainTool {
+  readonly id = 'porkbunRegisterDomain';
+  readonly name = 'porkbunRegisterDomain';
+  readonly displayName = 'Register Domain';
+  readonly description = 'Register and purchase a domain through Porkbun. WARNING: This is a REAL PURCHASE that will charge the payment method on file in the connected Porkbun account. The domain will be registered for the specified number of years (default: 1). Contact fields are optional — Porkbun uses account defaults if omitted.';
+  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 to register (e.g. "example.com")' },
+      years: { type: 'number', description: 'Number of years to register (default: 1, max: 10)' },
+      firstName: { type: 'string', description: 'Registrant first name (uses account default if omitted)' },
+      lastName: { type: 'string', description: 'Registrant last name (uses account default if omitted)' },
+      email: { type: 'string', description: 'Registrant email (uses account default if omitted)' },
+      phone: { type: 'string', description: 'Registrant phone number (uses account default if omitted)' },
+      city: { type: 'string', description: 'Registrant city (uses account default if omitted)' },
+      state: { type: 'string', description: 'Registrant state/province (uses account default if omitted)' },
+      zip: { type: 'string', description: 'Registrant postal code (uses account default if omitted)' },
+      country: { type: 'string', description: 'Registrant country code, e.g. "US" (uses account default if omitted)' },
+      organization: { type: 'string', description: 'Registrant organization (optional)' },
+      address: { type: 'string', description: 'Registrant street address (uses account default if omitted)' },
+    },
+    required: ['domain'],
+  };
+
+  constructor(private service: PorkbunService) {}
+
+  async execute(args: RegisterDomainInput): Promise<{ success: boolean; data?: RegisterDomainResult; error?: string }> {
+    try {
+      const result = await this.service.registerDomain({
+        domain: args.domain,
+        years: args.years,
+        firstName: args.firstName,
+        lastName: args.lastName,
+        email: args.email,
+        phone: args.phone,
+        city: args.city,
+        state: args.state,
+        zip: args.zip,
+        country: args.country,
+        organization: args.organization,
+        address: args.address,
+      });
+      return { success: true, data: result };
+    } catch (err: any) {
+      return { success: false, error: err.message };
+    }
+  }
+}

package/src/tools/searchDomain.ts

@@ -0,0 +1,39 @@
+// @ts-nocheck
+/**
+ * @fileoverview PorkbunSearchDomainTool — check domain availability and get pricing.
+ */
+
+import type { PorkbunService, DomainAvailability } from '../PorkbunService.js';
+
+export interface SearchDomainInput {
+  domain: string;
+}
+
+export class PorkbunSearchDomainTool {
+  readonly id = 'porkbunSearchDomain';
+  readonly name = 'porkbunSearchDomain';
+  readonly displayName = 'Search Domain Availability';
+  readonly description = 'Check if a domain name is available for registration on Porkbun and retrieve pricing information. Provide the full domain including TLD (e.g. "example.com", "mysite.dev").';
+  readonly category = 'domain';
+  readonly version = '0.1.0';
+  readonly hasSideEffects = false;
+
+  readonly inputSchema = {
+    type: 'object' as const,
+    properties: {
+      domain: { type: 'string', description: 'The domain name to check (e.g. "example.com", "coolsite.dev")' },
+    },
+    required: ['domain'],
+  };
+
+  constructor(private service: PorkbunService) {}
+
+  async execute(args: SearchDomainInput): Promise<{ success: boolean; data?: DomainAvailability; error?: string }> {
+    try {
+      const result = await this.service.checkAvailability(args.domain);
+      return { success: true, data: result };
+    } catch (err: any) {
+      return { success: false, error: err.message };
+    }
+  }
+}

package/src/tools/transferDomain.ts

@@ -0,0 +1,41 @@
+// @ts-nocheck
+/**
+ * @fileoverview PorkbunTransferDomainTool — initiate a domain transfer to Porkbun.
+ */
+
+import type { PorkbunService, TransferDomainResult } from '../PorkbunService.js';
+
+export interface TransferDomainInput {
+  domain: string;
+  authCode: string;
+}
+
+export class PorkbunTransferDomainTool {
+  readonly id = 'porkbunTransferDomain';
+  readonly name = 'porkbunTransferDomain';
+  readonly displayName = 'Transfer Domain';
+  readonly description = 'Initiate a domain transfer to Porkbun from another registrar. Requires the domain name and the authorization/EPP code from the current registrar. The domain must be unlocked at the current registrar before transferring.';
+  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 to transfer (e.g. "example.com")' },
+      authCode: { type: 'string', description: 'The authorization/EPP code from the current registrar (required to authorize the transfer)' },
+    },
+    required: ['domain', 'authCode'],
+  };
+
+  constructor(private service: PorkbunService) {}
+
+  async execute(args: TransferDomainInput): Promise<{ success: boolean; data?: TransferDomainResult; error?: string }> {
+    try {
+      const result = await this.service.transferDomain(args.domain, args.authCode);
+      return { success: true, data: result };
+    } catch (err: any) {
+      return { success: false, error: err.message };
+    }
+  }
+}

package/test/PorkbunService.test.ts

@@ -0,0 +1,434 @@
+// @ts-nocheck
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { PorkbunService, type PorkbunConfig } from '../src/PorkbunService';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function mockResponse(data: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? 'OK' : 'Error',
+    headers: new Headers(),
+    redirected: false,
+    type: 'basic' as ResponseType,
+    url: '',
+    clone: () => mockResponse(data, status),
+    body: null,
+    bodyUsed: false,
+    arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+    blob: () => Promise.resolve(new Blob()),
+    formData: () => Promise.resolve(new FormData()),
+    json: () => Promise.resolve(data),
+    text: () => Promise.resolve(JSON.stringify(data)),
+    bytes: () => Promise.resolve(new Uint8Array()),
+  } as Response;
+}
+
+const DEFAULT_CONFIG: PorkbunConfig = {
+  apiKey: 'pk_test_123',
+  secretApiKey: 'sk_test_456',
+  baseUrl: 'https://api.porkbun.com/api/json/v3',
+};
+
+let mockFetch: ReturnType<typeof vi.fn>;
+let service: PorkbunService;
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('PorkbunService', () => {
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    vi.stubGlobal('fetch', mockFetch);
+    service = new PorkbunService(DEFAULT_CONFIG);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // ── Constructor ──────────────────────────────────────────────────────────
+
+  it('should use default baseUrl when none is provided', () => {
+    const svc = new PorkbunService({ apiKey: 'a', secretApiKey: 'b' });
+    // Accessing private field via any to verify default
+    expect((svc as any).config.baseUrl).toBe('https://api.porkbun.com/api/json/v3');
+  });
+
+  it('should use custom baseUrl when provided', () => {
+    const svc = new PorkbunService({ apiKey: 'a', secretApiKey: 'b', baseUrl: 'https://custom.api.dev' });
+    expect((svc as any).config.baseUrl).toBe('https://custom.api.dev');
+  });
+
+  // ── initialize() ────────────────────────────────────────────────────────
+
+  it('should initialize successfully on ping SUCCESS', async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse({ status: 'SUCCESS', yourIp: '1.2.3.4' }));
+
+    await service.initialize();
+
+    expect(service.isRunning).toBe(true);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe('https://api.porkbun.com/api/json/v3/ping');
+    expect(init.method).toBe('POST');
+    const body = JSON.parse(init.body);
+    expect(body.apikey).toBe('pk_test_123');
+    expect(body.secretapikey).toBe('sk_test_456');
+  });
+
+  it('should throw on ping failure', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'ERROR', message: 'Invalid API key' }),
+    );
+
+    await expect(service.initialize()).rejects.toThrow('Porkbun auth failed');
+    expect(service.isRunning).toBe(false);
+  });
+
+  // ── shutdown() ──────────────────────────────────────────────────────────
+
+  it('should set isRunning to false on shutdown', async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse({ status: 'SUCCESS' }));
+    await service.initialize();
+    expect(service.isRunning).toBe(true);
+
+    await service.shutdown();
+    expect(service.isRunning).toBe(false);
+  });
+
+  // ── checkAvailability() ─────────────────────────────────────────────────
+
+  it('should return available=true when domain is available', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS', avail: true }),
+    );
+    // pricing call
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS', pricing: { registration: '9.73', renewal: '9.73', transfer: '9.73' } }),
+    );
+
+    const result = await service.checkAvailability('example.dev');
+
+    expect(result.domain).toBe('example.dev');
+    expect(result.available).toBe(true);
+    expect(result.pricing?.registration).toBe('9.73');
+  });
+
+  it('should return available=false when domain is taken', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS', avail: false }),
+    );
+    // pricing may fail for unavailable domains — mock failure
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'ERROR', message: 'No pricing' }),
+    );
+
+    const result = await service.checkAvailability('google.com');
+
+    expect(result.domain).toBe('google.com');
+    expect(result.available).toBe(false);
+    expect(result.pricing).toBeUndefined();
+  });
+
+  it('should handle string "true" for avail field', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS', avail: 'true' }),
+    );
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'ERROR', message: 'nope' }),
+    );
+
+    const result = await service.checkAvailability('test.io');
+    expect(result.available).toBe(true);
+  });
+
+  // ── getPricing() ────────────────────────────────────────────────────────
+
+  it('should return pricing for a domain', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS', pricing: { registration: '10.00', renewal: '10.00', transfer: '10.00', couponed: '8.00' } }),
+    );
+
+    const pricing = await service.getPricing('example.com');
+
+    expect(pricing.registration).toBe('10.00');
+    expect(pricing.renewal).toBe('10.00');
+    expect(pricing.transfer).toBe('10.00');
+    expect(pricing.couponed).toBe('8.00');
+  });
+
+  // ── registerDomain() ───────────────────────────────────────────────────
+
+  it('should register a domain successfully', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS', message: 'Domain registered' }),
+    );
+
+    const result = await service.registerDomain({ domain: 'newsite.dev', years: 2 });
+
+    expect(result.domain).toBe('newsite.dev');
+    expect(result.status).toBe('SUCCESS');
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.domain).toBe('newsite.dev');
+    expect(body.years).toBe(2);
+  });
+
+  it('should default to 1 year when years not specified', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS' }),
+    );
+
+    await service.registerDomain({ domain: 'newsite.dev' });
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.years).toBe(1);
+  });
+
+  it('should include optional contact fields', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS' }),
+    );
+
+    await service.registerDomain({
+      domain: 'newsite.dev',
+      firstName: 'John',
+      lastName: 'Doe',
+      email: 'john@example.com',
+      phone: '+1.5551234567',
+      city: 'New York',
+      state: 'NY',
+      zip: '10001',
+      country: 'US',
+      organization: 'Acme',
+      address: '123 Main St',
+    });
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.firstName).toBe('John');
+    expect(body.stateProvince).toBe('NY');
+    expect(body.addressLine1).toBe('123 Main St');
+    expect(body.organization).toBe('Acme');
+  });
+
+  // ── listDomains() ──────────────────────────────────────────────────────
+
+  it('should list all domains', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({
+        status: 'SUCCESS',
+        domains: [
+          {
+            domain: 'foo.dev',
+            status: 'ACTIVE',
+            tld: 'dev',
+            createDate: '2024-01-01',
+            expireDate: '2025-01-01',
+            securityLock: '1',
+            whoisPrivacy: true,
+            autoRenew: '1',
+            notLocal: '0',
+          },
+        ],
+      }),
+    );
+
+    const domains = await service.listDomains();
+
+    expect(domains).toHaveLength(1);
+    expect(domains[0].domain).toBe('foo.dev');
+    expect(domains[0].securityLock).toBe(true);
+    expect(domains[0].whoisPrivacy).toBe(true);
+    expect(domains[0].autoRenew).toBe(true);
+    expect(domains[0].notLocal).toBe(false);
+  });
+
+  it('should return empty array when no domains', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS' }),
+    );
+
+    const domains = await service.listDomains();
+    expect(domains).toEqual([]);
+  });
+
+  // ── createDnsRecord() ──────────────────────────────────────────────────
+
+  it('should create a DNS record and return its id', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS', id: '12345' }),
+    );
+
+    const result = await service.createDnsRecord('example.com', {
+      type: 'A',
+      content: '1.2.3.4',
+      name: 'www',
+    });
+
+    expect(result.id).toBe('12345');
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toContain('/dns/create/example.com');
+  });
+
+  // ── editDnsRecord() ────────────────────────────────────────────────────
+
+  it('should edit an existing DNS record', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS' }),
+    );
+
+    await service.editDnsRecord('example.com', '12345', {
+      content: '5.6.7.8',
+      ttl: '600',
+    });
+
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toContain('/dns/edit/example.com/12345');
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.content).toBe('5.6.7.8');
+    expect(body.ttl).toBe('600');
+  });
+
+  // ── deleteDnsRecord() ──────────────────────────────────────────────────
+
+  it('should delete a DNS record', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS' }),
+    );
+
+    await service.deleteDnsRecord('example.com', '12345');
+
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toContain('/dns/delete/example.com/12345');
+  });
+
+  // ── listDnsRecords() ──────────────────────────────────────────────────
+
+  it('should list DNS records for a domain', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({
+        status: 'SUCCESS',
+        records: [
+          { id: '1', name: 'www', type: 'A', content: '1.2.3.4', ttl: '300', prio: null, notes: null },
+          { id: '2', name: 'mail', type: 'MX', content: 'mx.example.com', ttl: '600', prio: '10', notes: 'Primary MX' },
+        ],
+      }),
+    );
+
+    const records = await service.listDnsRecords('example.com');
+
+    expect(records).toHaveLength(2);
+    expect(records[0].id).toBe('1');
+    expect(records[0].type).toBe('A');
+    expect(records[1].prio).toBe('10');
+    expect(records[1].notes).toBe('Primary MX');
+  });
+
+  // ── getDnsRecordsByNameType() ──────────────────────────────────────────
+
+  it('should retrieve DNS records by name and type', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({
+        status: 'SUCCESS',
+        records: [
+          { id: '3', name: 'www', type: 'A', content: '1.2.3.4', ttl: '300' },
+        ],
+      }),
+    );
+
+    const records = await service.getDnsRecordsByNameType('example.com', 'A', 'www');
+
+    expect(records).toHaveLength(1);
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toContain('/dns/retrieveByNameType/example.com/A/www');
+  });
+
+  it('should use empty subdomain when not specified', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS', records: [] }),
+    );
+
+    await service.getDnsRecordsByNameType('example.com', 'CNAME');
+
+    const [url] = mockFetch.mock.calls[0];
+    expect(url).toContain('/dns/retrieveByNameType/example.com/CNAME/');
+  });
+
+  // ── transferDomain() ───────────────────────────────────────────────────
+
+  it('should initiate a domain transfer', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS', message: 'Transfer initiated' }),
+    );
+
+    const result = await service.transferDomain('example.com', 'AUTH123');
+
+    expect(result.domain).toBe('example.com');
+    expect(result.status).toBe('SUCCESS');
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.domain).toBe('example.com');
+    expect(body.authCode).toBe('AUTH123');
+  });
+
+  // ── Error handling ─────────────────────────────────────────────────────
+
+  it('should throw on HTTP error with message from response', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'ERROR', message: 'Unauthorized' }, 401),
+    );
+
+    await expect(service.checkAvailability('test.com')).rejects.toThrow(
+      'Porkbun API 401: Unauthorized',
+    );
+  });
+
+  it('should throw on invalid JSON response', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: () => Promise.resolve('not json'),
+    } as any);
+
+    await expect(service.checkAvailability('test.com')).rejects.toThrow(
+      'invalid JSON',
+    );
+  });
+
+  it('should throw on API-level ERROR status', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'ERROR', message: 'Domain not found' }),
+    );
+
+    await expect(service.listDnsRecords('nonexistent.com')).rejects.toThrow(
+      'Porkbun API error: Domain not found',
+    );
+  });
+
+  // ── Auth payload ──────────────────────────────────────────────────────
+
+  it('should include apikey and secretapikey in every POST body', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS', domains: [] }),
+    );
+
+    await service.listDomains();
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.apikey).toBe('pk_test_123');
+    expect(body.secretapikey).toBe('sk_test_456');
+  });
+
+  it('should always use POST method', async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ status: 'SUCCESS', domains: [] }),
+    );
+
+    await service.listDomains();
+
+    expect(mockFetch.mock.calls[0][1].method).toBe('POST');
+  });
+});

package/test/index.test.ts

@@ -0,0 +1,50 @@
+// @ts-nocheck
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createExtensionPack } from '../src/index.js';
+
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+function okResponse(data: any = {}) {
+  return { ok: true, status: 200, text: async () => JSON.stringify({ status: 'SUCCESS', ...data }), json: async () => ({ status: 'SUCCESS', ...data }) } as Response;
+}
+
+describe('createExtensionPack (Porkbun)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockFetch.mockResolvedValue(okResponse({ yourIp: '1.2.3.4' }));
+  });
+
+  it('should return a valid ExtensionPack', () => {
+    const pack = createExtensionPack({ secrets: { 'porkbun.apiKey': 'ak', 'porkbun.secretApiKey': 'sak' } });
+    expect(pack.name).toBe('@framers/agentos-ext-domain-porkbun');
+    expect(pack.version).toBe('0.1.0');
+    expect(pack.descriptors).toHaveLength(5);
+  });
+
+  it('should register correct tool IDs', () => {
+    const pack = createExtensionPack({ secrets: { 'porkbun.apiKey': 'ak', 'porkbun.secretApiKey': 'sak' } });
+    const ids = pack.descriptors.map((d) => d.id);
+    expect(ids).toContain('porkbunSearchDomain');
+    expect(ids).toContain('porkbunRegisterDomain');
+    expect(ids).toContain('porkbunListDomains');
+    expect(ids).toContain('porkbunConfigureDns');
+    expect(ids).toContain('porkbunTransferDomain');
+  });
+
+  it('onActivate should throw without credentials', async () => {
+    const pack = createExtensionPack({ secrets: {} });
+    await expect(pack.onActivate!()).rejects.toThrow();
+  });
+
+  it('onActivate should succeed with valid credentials', async () => {
+    const pack = createExtensionPack({ secrets: { 'porkbun.apiKey': 'ak', 'porkbun.secretApiKey': 'sak' } });
+    await expect(pack.onActivate!()).resolves.toBeUndefined();
+  });
+
+  it('onDeactivate should complete', async () => {
+    const pack = createExtensionPack({ secrets: { 'porkbun.apiKey': 'ak', 'porkbun.secretApiKey': 'sak' } });
+    await pack.onActivate!();
+    await expect(pack.onDeactivate!()).resolves.toBeUndefined();
+  });
+});