agentdex-cli 0.1.0

package/dist/nostr.js

@@ -0,0 +1,115 @@
+/**
+ * Nostr utilities — event creation, signing, publishing
+ */
+import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
+import { nip19 } from 'nostr-tools';
+import { SimplePool } from 'nostr-tools/pool';
+const DEFAULT_RELAYS = ['wss://nos.lol', 'wss://relay.damus.io'];
+/**
+ * Parse a secret key from nsec, hex, or key file
+ */
+export function parseSecretKey(input) {
+    // If it's an nsec
+    if (input.startsWith('nsec')) {
+        const decoded = nip19.decode(input);
+        if (decoded.type !== 'nsec')
+            throw new Error('Invalid nsec');
+        return decoded.data;
+    }
+    // Hex string
+    if (/^[0-9a-f]{64}$/i.test(input)) {
+        return Uint8Array.from(Buffer.from(input, 'hex'));
+    }
+    throw new Error('Invalid key format. Provide nsec or 64-char hex.');
+}
+/**
+ * Get npub from secret key
+ */
+export function getNpub(sk) {
+    const pubHex = getPublicKey(sk);
+    return nip19.npubEncode(pubHex);
+}
+/**
+ * Get hex pubkey from secret key
+ */
+export function getPubkeyHex(sk) {
+    return getPublicKey(sk);
+}
+/**
+ * Build and sign a kind 31337 agent profile event
+ */
+export function createProfileEvent(sk, profile) {
+    const tags = [
+        ['d', 'agentdex-profile'],
+        ['name', profile.name],
+    ];
+    if (profile.description)
+        tags.push(['description', profile.description]);
+    if (profile.capabilities) {
+        for (const cap of profile.capabilities) {
+            tags.push(['capability', cap]);
+        }
+    }
+    if (profile.framework)
+        tags.push(['framework', profile.framework]);
+    if (profile.model)
+        tags.push(['model', profile.model]);
+    if (profile.website)
+        tags.push(['website', profile.website]);
+    if (profile.avatar)
+        tags.push(['avatar', profile.avatar]);
+    if (profile.lightning)
+        tags.push(['lightning', profile.lightning]);
+    if (profile.human)
+        tags.push(['human', profile.human]);
+    if (profile.ownerX)
+        tags.push(['owner_x', profile.ownerX]);
+    if (profile.status)
+        tags.push(['status', profile.status || 'active']);
+    if (profile.messagingPolicy)
+        tags.push(['messaging_policy', profile.messagingPolicy]);
+    if (profile.messagingMinTrust)
+        tags.push(['messaging_min_trust', String(profile.messagingMinTrust)]);
+    if (profile.messagingFee)
+        tags.push(['messaging_fee', String(profile.messagingFee)]);
+    const event = finalizeEvent({
+        kind: 31337,
+        created_at: Math.floor(Date.now() / 1000),
+        tags,
+        content: '',
+    }, sk);
+    return event;
+}
+/**
+ * Publish an event to Nostr relays
+ */
+export async function publishToRelays(event, relays = DEFAULT_RELAYS) {
+    const pool = new SimplePool();
+    const published = [];
+    try {
+        const results = await Promise.allSettled(relays.map(async (relay) => {
+            await pool.publish([relay], event);
+            return relay;
+        }));
+        for (const result of results) {
+            if (result.status === 'fulfilled') {
+                published.push(result.value);
+            }
+        }
+    }
+    finally {
+        pool.close(relays);
+    }
+    return published;
+}
+/**
+ * Create and sign a kind 1 note tagged #agentdex
+ */
+export function createNote(sk, content) {
+    return finalizeEvent({
+        kind: 1,
+        created_at: Math.floor(Date.now() / 1000),
+        tags: [['t', 'agentdex']],
+        content,
+    }, sk);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "agentdex-cli",
+  "version": "0.1.0",
+  "description": "CLI and SDK for the agentdex AI agent directory",
+  "type": "module",
+  "bin": {
+    "agentdex": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["agentdex", "nostr", "ai", "agent", "directory", "nip-05"],
+  "author": "Koda <kodabuilds@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Koda-Builds/agentdex-cli"
+  },
+  "dependencies": {
+    "nostr-tools": "^2.10.4",
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.0",
+    "inquirer": "^9.2.0",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^22.0.0",
+    "@types/inquirer": "^9.0.0",
+    "@types/qrcode-terminal": "^0.12.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import inquirer from 'inquirer';
+import qrcode from 'qrcode-terminal';
+import { readFileSync } from 'fs';
+import { AgentdexClient } from './client.js';
+import { parseSecretKey, getNpub, getPubkeyHex, createProfileEvent, publishToRelays, createNote } from './nostr.js';
+
+const program = new Command();
+
+program
+  .name('agentdex')
+  .description('CLI for the agentdex AI agent directory')
+  .version('0.1.0');
+
+/**
+ * Resolve secret key from flags, env, or key file
+ */
+function resolveKey(options: { nsec?: string; keyFile?: string }): Uint8Array {
+  const raw = options.nsec || process.env.NOSTR_NSEC;
+  if (raw) return parseSecretKey(raw);
+
+  if (options.keyFile) {
+    const data = JSON.parse(readFileSync(options.keyFile, 'utf-8'));
+    if (data.sk_hex) return parseSecretKey(data.sk_hex);
+    if (data.nsec) return parseSecretKey(data.nsec);
+    throw new Error('Key file must contain sk_hex or nsec');
+  }
+
+  throw new Error('No key provided. Use --nsec, --key-file, or set NOSTR_NSEC env var.');
+}
+
+// ==================== REGISTER ====================
+
+program
+  .command('register')
+  .description('Register your agent on agentdex')
+  .option('--nsec <nsec>', 'Nostr secret key (nsec or hex)')
+  .option('--key-file <path>', 'Path to JSON key file')
+  .option('--name <name>', 'Agent name')
+  .option('--description <desc>', 'Agent description')
+  .option('--capabilities <caps>', 'Comma-separated capabilities')
+  .option('--framework <fw>', 'Framework (e.g., langchain, openclaw)')
+  .option('--model <model>', 'Model (e.g., claude-3.5-sonnet)')
+  .option('--website <url>', 'Website URL')
+  .option('--lightning <addr>', 'Lightning address')
+  .option('--owner-x <handle>', 'Owner X/Twitter handle (e.g., @username)')
+  .option('--api-key <key>', 'Agentdex API key')
+  .option('--relay <url>', 'Additional relay (repeatable)', (val: string, acc: string[]) => [...acc, val], [])
+  .option('--json', 'Output JSON')
+  .action(async (options) => {
+    try {
+      const sk = resolveKey(options);
+      const npub = getNpub(sk);
+      const pubHex = getPubkeyHex(sk);
+
+      let name = options.name;
+      let description = options.description;
+      let capabilities = options.capabilities?.split(',').map((s: string) => s.trim());
+      let framework = options.framework;
+
+      // Interactive mode if name not provided
+      if (!name) {
+        const answers = await inquirer.prompt([
+          { type: 'input', name: 'name', message: 'Agent name:', validate: (v: string) => v.length > 0 || 'Required' },
+          { type: 'input', name: 'description', message: 'Description (optional):' },
+          { type: 'input', name: 'capabilities', message: 'Capabilities (comma-separated):' },
+          { type: 'input', name: 'framework', message: 'Framework (optional):' },
+        ]);
+        name = answers.name;
+        description = answers.description || description;
+        capabilities = answers.capabilities ? answers.capabilities.split(',').map((s: string) => s.trim()) : capabilities;
+        framework = answers.framework || framework;
+      }
+
+      const spinner = ora('Signing event...').start();
+
+      const event = createProfileEvent(sk, {
+        name,
+        description,
+        capabilities,
+        framework,
+        model: options.model,
+        website: options.website,
+        lightning: options.lightning,
+        ownerX: options.ownerX,
+        status: 'active',
+      });
+
+      spinner.text = 'Registering on agentdex...';
+      const client = new AgentdexClient({ apiKey: options.apiKey });
+
+      try {
+        const result = await client.register(event);
+
+        spinner.text = 'Publishing to Nostr relays...';
+        const relays = ['wss://nos.lol', 'wss://relay.damus.io', ...options.relay];
+        const published = await publishToRelays(event, relays);
+
+        spinner.succeed('Registered!');
+
+        if (options.json) {
+          console.log(JSON.stringify({ ...result, relays: published }, null, 2));
+        } else {
+          console.log('');
+          console.log(chalk.hex('#D4A574')('  ✅ Registered on agentdex (free tier)'));
+          console.log(chalk.gray(`  npub: ${npub}`));
+          console.log(chalk.gray(`  Name: ${name}`));
+          console.log(chalk.gray(`  Published to: ${published.join(', ')}`));
+          console.log('');
+          console.log(chalk.gray(`  Run ${chalk.white('agentdex claim <name>')} to get ${chalk.hex('#D4A574')('<name>@agentdex.id')}`));
+          console.log('');
+          console.log(chalk.gray('  Next: Claim a NIP-05 name to get verified (first 100 free, then 5000 sats).'));
+        }
+      } catch (err) {
+        spinner.fail(`Registration failed: ${(err as Error).message}`);
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error(chalk.red(`Error: ${(err as Error).message}`));
+      process.exit(1);
+    }
+  });
+
+// ==================== CLAIM ====================
+
+program
+  .command('claim <name>')
+  .description('Claim a NIP-05 name (name@agentdex.id)')
+  .option('--nsec <nsec>', 'Nostr secret key')
+  .option('--key-file <path>', 'Path to JSON key file')
+  .option('--nwc <uri>', 'Nostr Wallet Connect URI for auto-pay')
+  .option('--api-key <key>', 'Agentdex API key')
+  .option('--json', 'Output JSON')
+  .action(async (name: string, options) => {
+    try {
+      const sk = resolveKey(options);
+      const client = new AgentdexClient({ apiKey: options.apiKey });
+
+      const spinner = ora(`Claiming ${name}@agentdex.id...`).start();
+
+      // Sign a kind 31337 event for claim authentication
+      const event = createProfileEvent(sk, {
+        name,
+        status: 'active',
+      });
+
+      const claim = await client.claim(name, event);
+
+      // Free/successful claim
+      if (claim.claimed) {
+        spinner.succeed(`${chalk.hex('#D4A574')(`${claim.nip05}`)} is now active!`);
+        if (claim.next_steps) {
+          console.log('');
+          const ns = claim.next_steps as Record<string, { description?: string; relays?: string[] }>;
+          if (ns.publish_kind0) {
+            console.log(chalk.gray(`  Next: ${ns.publish_kind0.description}`));
+            if (ns.publish_kind0.relays) {
+              console.log(chalk.gray(`  Relays: ${ns.publish_kind0.relays.join(', ')}`));
+            }
+          }
+        }
+        return;
+      }
+
+      // Payment required (402)
+      if (claim.status === 'awaiting_payment' && claim.invoice) {
+        spinner.stop();
+        console.log('');
+        console.log(chalk.hex('#D4A574')(`  💰 Claim ${name}@agentdex.id for ${claim.amount_sats?.toLocaleString()} sats`));
+        console.log('');
+
+        qrcode.generate(claim.invoice, { small: true }, (qr: string) => {
+          console.log(qr);
+        });
+        console.log(chalk.gray(`  bolt11: ${claim.invoice}`));
+        console.log('');
+
+        if (options.nwc) {
+          console.log(chalk.gray('  Auto-paying via NWC...'));
+          console.log(chalk.yellow('  NWC auto-pay not yet implemented. Pay the invoice manually.'));
+        }
+
+        // Poll for payment
+        const pollSpinner = ora('Waiting for payment...').start();
+        const startTime = Date.now();
+        const timeout = 15 * 60 * 1000;
+
+        while (Date.now() - startTime < timeout) {
+          await new Promise((r) => setTimeout(r, 3000));
+          const status = await client.claimStatus(claim.payment_hash!);
+          if (status.paid) {
+            pollSpinner.succeed(`${chalk.hex('#D4A574')(`${name}@agentdex.id`)} is now active!`);
+            return;
+          }
+        }
+
+        pollSpinner.fail('Payment timeout (15 min). Invoice expired.');
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error(chalk.red(`Error: ${(err as Error).message}`));
+      process.exit(1);
+    }
+  });
+
+// ==================== VERIFY ====================
+
+program
+  .command('verify <npub>')
+  .description('Check if an agent is registered on agentdex')
+  .option('--json', 'Output JSON')
+  .action(async (npub: string, options) => {
+    try {
+      const client = new AgentdexClient();
+      const spinner = ora('Verifying...').start();
+
+      const result = await client.verify(npub);
+
+      if (options.json) {
+        spinner.stop();
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      if (result.registered) {
+        spinner.succeed('Registered on agentdex');
+        console.log(chalk.gray(`  Name: ${result.name}`));
+        console.log(chalk.gray(`  Trust Score: ${result.trustScore}`));
+        console.log(chalk.gray(`  Capabilities: ${result.capabilities.join(', ') || 'none'}`));
+        console.log(chalk.gray(`  Nostr: ${result.hasNostr ? '✅' : '❌'}  Agentdex: ${result.hasAgentdex ? '✅' : '❌'}`));
+      } else {
+        spinner.warn('Not registered on agentdex');
+      }
+    } catch (err) {
+      console.error(chalk.red(`Error: ${(err as Error).message}`));
+      process.exit(1);
+    }
+  });
+
+// ==================== SEARCH ====================
+
+program
+  .command('search [query]')
+  .description('Search the agentdex directory')
+  .option('--capability <cap>', 'Filter by capability')
+  .option('--framework <fw>', 'Filter by framework')
+  .option('--min-trust <score>', 'Minimum trust score')
+  .option('--limit <n>', 'Max results', '10')
+  .option('--json', 'Output JSON')
+  .action(async (query: string | undefined, options) => {
+    try {
+      const client = new AgentdexClient();
+      const spinner = ora('Searching...').start();
+
+      const agents = await client.search({
+        q: query,
+        capability: options.capability,
+        framework: options.framework,
+        limit: parseInt(options.limit),
+      }) as any[];
+
+      spinner.stop();
+
+      if (options.json) {
+        console.log(JSON.stringify(agents, null, 2));
+        return;
+      }
+
+      if (agents.length === 0) {
+        console.log(chalk.gray('No agents found.'));
+        return;
+      }
+
+      for (const agent of agents) {
+        const trust = agent.trustScore ? chalk.hex('#D4A574')(`[${agent.trustScore}]`) : '';
+        console.log(`${chalk.white(agent.name)} ${trust} ${chalk.gray(agent.npub?.substring(0, 20) + '...')}`);
+        if (agent.description) console.log(chalk.gray(`  ${agent.description.substring(0, 80)}`));
+        if (agent.capabilities?.length) console.log(chalk.gray(`  ${agent.capabilities.join(', ')}`));
+        console.log('');
+      }
+
+      console.log(chalk.gray(`${agents.length} agents found`));
+    } catch (err) {
+      console.error(chalk.red(`Error: ${(err as Error).message}`));
+      process.exit(1);
+    }
+  });
+
+// ==================== WHOAMI ====================
+
+program
+  .command('whoami')
+  .description('Show your agent profile')
+  .option('--nsec <nsec>', 'Nostr secret key')
+  .option('--key-file <path>', 'Path to JSON key file')
+  .action(async (options) => {
+    try {
+      const sk = resolveKey(options);
+      const npub = getNpub(sk);
+      const client = new AgentdexClient();
+
+      const spinner = ora('Looking up...').start();
+      const result = await client.verify(npub);
+      spinner.stop();
+
+      if (result.registered) {
+        console.log(chalk.hex('#D4A574')(`  ${result.name}`));
+        console.log(chalk.gray(`  ${npub}`));
+        console.log(chalk.gray(`  Trust: ${result.trustScore}`));
+        console.log(chalk.gray(`  Nostr: ${result.hasNostr ? '✅' : '❌'}  Agentdex: ${result.hasAgentdex ? '✅' : '❌'}`));
+        console.log(chalk.gray(`  Capabilities: ${result.capabilities.join(', ') || 'none'}`));
+      } else {
+        console.log(chalk.yellow('  Not registered on agentdex yet.'));
+        console.log(chalk.gray(`  npub: ${npub}`));
+        console.log(chalk.gray(`  Run: agentdex register`));
+      }
+    } catch (err) {
+      console.error(chalk.red(`Error: ${(err as Error).message}`));
+      process.exit(1);
+    }
+  });
+
+// ==================== PUBLISH ====================
+
+program
+  .command('publish <message>')
+  .description('Publish a note tagged #agentdex')
+  .option('--nsec <nsec>', 'Nostr secret key')
+  .option('--key-file <path>', 'Path to JSON key file')
+  .option('--relay <url>', 'Additional relay', (val: string, acc: string[]) => [...acc, val], [])
+  .action(async (message: string, options) => {
+    try {
+      const sk = resolveKey(options);
+      const spinner = ora('Publishing...').start();
+
+      const event = createNote(sk, message);
+      const relays = ['wss://nos.lol', 'wss://relay.damus.io', ...options.relay];
+      const published = await publishToRelays(event, relays);
+
+      spinner.succeed('Published!');
+      console.log(chalk.gray(`  Published to: ${published.join(', ')}`));
+      console.log(chalk.gray(`  Event ID: ${(event as any).id}`));
+    } catch (err) {
+      console.error(chalk.red(`Error: ${(err as Error).message}`));
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/client.ts

@@ -0,0 +1,134 @@
+/**
+ * AgentdexClient — SDK for interacting with the agentdex API
+ */
+
+export interface AgentdexConfig {
+  baseUrl?: string;
+  apiKey?: string;
+}
+
+export interface RegisterOptions {
+  name: string;
+  description?: string;
+  capabilities?: string[];
+  framework?: string;
+  model?: string;
+  website?: string;
+  avatar?: string;
+  lightning?: string;
+  human?: string;
+  status?: string;
+  messagingPolicy?: string;
+  messagingMinTrust?: number;
+  messagingFee?: number;
+}
+
+export interface VerifyResult {
+  registered: boolean;
+  hasNostr: boolean;
+  hasAgentdex: boolean;
+  trustScore: number;
+  name: string | null;
+  npub: string | null;
+  capabilities: string[];
+  messagingPolicy: string | null;
+}
+
+export interface ClaimResult {
+  // Free/successful claim
+  claimed?: boolean;
+  nip05?: string;
+  agent?: { id: string; name: string; nip05Name: string; tier: string };
+  next_steps?: Record<string, unknown>;
+  // Paid claim (402)
+  status?: string;
+  invoice?: string;
+  payment_hash?: string;
+  amount_sats?: number;
+  expires_at?: string;
+}
+
+export interface ClaimStatus {
+  paid: boolean;
+  name?: string;
+  nip05?: string;
+}
+
+export interface SearchOptions {
+  q?: string;
+  capability?: string;
+  framework?: string;
+  status?: string;
+  sourceFilter?: string;
+  sort?: string;
+  limit?: number;
+}
+
+export class AgentdexClient {
+  private baseUrl: string;
+  private apiKey?: string;
+
+  constructor(config: AgentdexConfig = {}) {
+    this.baseUrl = (config.baseUrl || process.env.AGENTDEX_URL || 'https://agentdex.id').replace(/\/$/, '');
+    this.apiKey = config.apiKey || process.env.AGENTDEX_API_KEY;
+  }
+
+  private async fetch(path: string, options: RequestInit = {}): Promise<Response> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...(options.headers as Record<string, string> || {}),
+    };
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+    return fetch(`${this.baseUrl}${path}`, { ...options, headers });
+  }
+
+  async verify(pubkeyOrNpub: string): Promise<VerifyResult> {
+    const param = pubkeyOrNpub.startsWith('npub') ? 'npub' : 'pubkey';
+    const res = await this.fetch(`/api/v1/agents/verify?${param}=${encodeURIComponent(pubkeyOrNpub)}`);
+    return res.json();
+  }
+
+  async register(event: object): Promise<{ agent: object; registered: boolean; tier: string }> {
+    const res = await this.fetch('/api/v1/agents/register', {
+      method: 'POST',
+      body: JSON.stringify({ event }),
+    });
+    if (!res.ok) {
+      const err = await res.json();
+      throw new Error(err.error || 'Registration failed');
+    }
+    return res.json();
+  }
+
+  async claim(name: string, event: object): Promise<ClaimResult> {
+    const res = await this.fetch('/api/v1/agents/claim', {
+      method: 'POST',
+      body: JSON.stringify({ name, event }),
+    });
+    if (!res.ok && res.status !== 402) {
+      const err = await res.json();
+      throw new Error(err.error || 'Claim failed');
+    }
+    return res.json();
+  }
+
+  async claimStatus(paymentHash: string): Promise<ClaimStatus> {
+    const res = await this.fetch(`/api/v1/agents/claim/status?payment_hash=${encodeURIComponent(paymentHash)}`);
+    return res.json();
+  }
+
+  async search(options: SearchOptions = {}): Promise<object[]> {
+    const params = new URLSearchParams();
+    if (options.q) params.set('q', options.q);
+    if (options.capability) params.set('capability', options.capability);
+    if (options.framework) params.set('framework', options.framework);
+    if (options.status) params.set('status', options.status);
+    if (options.sourceFilter) params.set('source_filter', options.sourceFilter);
+    if (options.sort) params.set('sort', options.sort);
+    if (options.limit) params.set('limit', String(options.limit));
+    const res = await this.fetch(`/api/v1/agents?${params}`);
+    return res.json();
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * agentdex — SDK and CLI for the agentdex AI agent directory
+ * 
+ * @example
+ * ```typescript
+ * import { AgentdexClient } from 'agentdex';
+ * 
+ * const client = new AgentdexClient({ apiKey: 'adx_...' });
+ * const result = await client.verify('npub1...');
+ * ```
+ */
+
+export { AgentdexClient } from './client.js';
+export type {
+  AgentdexConfig,
+  RegisterOptions,
+  VerifyResult,
+  ClaimResult,
+  ClaimStatus,
+  SearchOptions,
+} from './client.js';
+
+export {
+  parseSecretKey,
+  getNpub,
+  getPubkeyHex,
+  createProfileEvent,
+  publishToRelays,
+  createNote,
+} from './nostr.js';
+export type { AgentProfile } from './nostr.js';