netlibrary-cli 1.0.0

package/bin/netlibrary.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const output = require('../lib/output');
+
+program
+  .name('netlibrary')
+  .description('Net Library CLI — interact with the decentralized digital library on Base')
+  .version('1.0.0')
+  .option('--json', 'Output raw JSON (for programmatic/agent use)')
+  .option('--api-key <key>', 'Override API key')
+  .option('--base-url <url>', 'Override base URL')
+  .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.optsWithGlobals();
+    if (opts.json) output.setJsonMode(true);
+    if (opts.apiKey) process.env.NETLIB_API_KEY = opts.apiKey;
+    if (opts.baseUrl) process.env.NETLIB_BASE_URL = opts.baseUrl;
+  });
+
+require('../commands/config')(program);
+require('../commands/library')(program);
+require('../commands/search')(program);
+require('../commands/stacks')(program);
+require('../commands/member')(program);
+require('../commands/agents')(program);
+require('../commands/tasks')(program);
+require('../commands/archive')(program);
+require('../commands/stats')(program);
+require('../commands/embeds')(program);
+require('../commands/info')(program);
+require('../commands/comments')(program);
+
+program.parse();

package/commands/agents.js

@@ -0,0 +1,173 @@
+const api = require('../lib/api');
+const output = require('../lib/output');
+const config = require('../lib/config');
+
+module.exports = function (program) {
+  const cmd = program.command('agents').description('Agent management');
+
+  cmd
+    .command('me')
+    .description('View your agent profile and widgets')
+    .action(async () => {
+      try {
+        const data = await api.get('/agents/me');
+        if (output.isJsonMode()) {
+          output.json(data);
+          return;
+        }
+        const agent = data.agent || {};
+        const profile = agent.profile || {};
+        const membership = data.membership || {};
+        output.item({}, [
+          ['ID', () => agent.id],
+          ['Name', () => profile.name || agent.name],
+          ['Address', () => agent.address],
+          ['FID', () => agent.fid],
+          ['Permissions', () => (agent.permissions || []).join(', ')],
+          ['Created', () => agent.createdAt ? new Date(agent.createdAt).toLocaleString() : null],
+        ]);
+
+        if (membership.memberId) {
+          console.log('\nMembership:');
+          output.item(membership, [
+            ['Member ID', 'memberId'],
+            ['ENS', 'ensSubname'],
+            ['Since', 'memberSince', v => v ? new Date(v).toLocaleDateString() : null],
+          ]);
+        }
+
+        if (data.widgets) {
+          console.log('\nWidgets:');
+          const w = data.widgets;
+          if (w.libraryCard) console.log(`  Library Card: ${w.libraryCard.url}`);
+          if (w.profile) console.log(`  Profile:      ${w.profile.url}`);
+          if (w.stacks && w.stacks.length > 0) {
+            w.stacks.forEach(s => console.log(`  Stack:        ${s.url} (${s.name})`));
+          }
+        }
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('register')
+    .description('Register a new agent (admin only)')
+    .requiredOption('--id <id>', 'Agent ID (lowercase, alphanumeric + hyphens)')
+    .requiredOption('--name <name>', 'Agent display name')
+    .option('--permissions <perms...>', 'Permissions', ['library:write', 'stacks:create', 'stacks:write'])
+    .option('--address <addr>', 'Wallet address')
+    .option('--description <desc>', 'Description')
+    .option('--fid <n>', 'Farcaster FID')
+    .option('--pfp-url <url>', 'Profile picture URL')
+    .option('--webhook-url <url>', 'Webhook URL')
+    .action(async (opts) => {
+      try {
+        const cfg = config.load();
+        const adminKey = process.env.NETLIB_ADMIN_KEY || cfg.adminKey;
+        if (!adminKey) {
+          output.error('Admin key required. Set with: netlibrary config set admin-key <key>');
+          process.exit(1);
+        }
+
+        const body = {
+          id: opts.id,
+          name: opts.name,
+          permissions: opts.permissions,
+        };
+        if (opts.address) body.address = opts.address;
+        if (opts.description) body.description = opts.description;
+        if (opts.fid) body.fid = parseInt(opts.fid);
+        if (opts.pfpUrl) body.pfpUrl = opts.pfpUrl;
+        if (opts.webhookUrl) body.webhookUrl = opts.webhookUrl;
+
+        const data = await api.post('/agents', body, {
+          headers: { 'Authorization': `Bearer ${adminKey}` },
+          auth: false,
+        });
+
+        output.success(`Agent "${opts.id}" registered!`);
+        if (data.agent?.apiKey) {
+          console.log(`\nAPI Key: ${data.agent.apiKey}`);
+          console.log('Save this key — it cannot be retrieved again!');
+        }
+        if (output.isJsonMode()) output.json(data);
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('list')
+    .description('List all agents (admin only)')
+    .action(async () => {
+      try {
+        const data = await api.get('/agents');
+        output.table(
+          ['ID', 'Name', 'Address', 'Permissions', 'Active'],
+          (data.agents || []).map(a => [
+            a.id,
+            a.name || '—',
+            a.address ? a.address.slice(0, 10) + '...' : '—',
+            (a.permissions || []).join(', '),
+            a.isActive ? 'Yes' : 'No',
+          ])
+        );
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('update')
+    .description('Update your agent profile')
+    .option('--name <name>', 'Display name')
+    .option('--description <desc>', 'Description')
+    .option('--address <addr>', 'Wallet address')
+    .option('--pfp-url <url>', 'Profile picture URL')
+    .option('--webhook-url <url>', 'Webhook URL')
+    .option('--fid <n>', 'Farcaster FID')
+    .option('--8004-token-id <n>', 'ERC-8004 token ID')
+    .option('--id <agentId>', 'Target agent ID (admin only)')
+    .action(async (opts) => {
+      try {
+        const body = {};
+        if (opts.id) body.id = opts.id;
+        if (opts.name) body.name = opts.name;
+        if (opts.description) body.description = opts.description;
+        if (opts.address) body.address = opts.address;
+        if (opts.pfpUrl) body.pfpUrl = opts.pfpUrl;
+        if (opts.webhookUrl) body.webhookUrl = opts.webhookUrl;
+        if (opts.fid) body.fid = parseInt(opts.fid);
+        if (opts['8004TokenId']) body.erc8004TokenId = parseInt(opts['8004TokenId']);
+
+        const data = await api.put('/agents', body);
+        output.success('Agent updated');
+        if (data.erc8004Verification) {
+          if (data.erc8004Verification.verified) {
+            output.success(`ERC-8004 verified! Token ID: ${data.erc8004Verification.tokenId}`);
+          }
+        }
+        if (output.isJsonMode()) output.json(data);
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('deactivate <agentId>')
+    .description('Deactivate an agent (admin only)')
+    .action(async (agentId) => {
+      try {
+        const data = await api.del('/agents', { id: agentId });
+        output.success(`Agent "${agentId}" deactivated`);
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+};

package/commands/archive.js

@@ -0,0 +1,40 @@
+const api = require('../lib/api');
+const output = require('../lib/output');
+
+module.exports = function (program) {
+  program
+    .command('archive [castHash]')
+    .description('Archive a Farcaster cast as a library item')
+    .option('--cast-url <url>', 'Warpcast URL (alternative to castHash)')
+    .option('--text <text>', 'Cast text content')
+    .option('--title <title>', 'Custom title')
+    .option('-c, --category <cat...>', 'Additional categories')
+    .option('--author-fid <n>', 'Author FID')
+    .option('--author-username <name>', 'Author username')
+    .option('--add-to-stack <stackId>', 'Add to stack after archiving')
+    .action(async (castHash, opts) => {
+      try {
+        if (!castHash && !opts.castUrl) {
+          output.error('Provide a cast hash or --cast-url');
+          process.exit(1);
+        }
+
+        const body = {};
+        if (castHash) body.castHash = castHash;
+        if (opts.castUrl) body.castUrl = opts.castUrl;
+        if (opts.text) body.text = opts.text;
+        if (opts.title) body.title = opts.title;
+        if (opts.category) body.categories = opts.category;
+        if (opts.authorFid) body.authorFid = parseInt(opts.authorFid);
+        if (opts.authorUsername) body.authorUsername = opts.authorUsername;
+        if (opts.addToStack) body.addToStack = opts.addToStack;
+
+        const data = await api.post('/archive', body);
+        output.success(`Archived: ${data.contentKey}`);
+        if (output.isJsonMode()) output.json(data);
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+};

package/commands/comments.js

@@ -0,0 +1,49 @@
+const api = require('../lib/api');
+const output = require('../lib/output');
+const chalk = require('chalk');
+
+module.exports = function (program) {
+  program
+    .command('comments <contentKey>')
+    .description('View comments for a library item')
+    .option('--parent-id <id>', 'Get replies to a specific comment')
+    .action(async (contentKey, opts) => {
+      try {
+        const data = await api.get(`/comments/${encodeURIComponent(contentKey)}`, {
+          query: { parentId: opts.parentId },
+          auth: false,
+        });
+
+        if (output.isJsonMode()) {
+          output.json(data);
+          return;
+        }
+
+        if (data.item) {
+          console.log(`Comments for: ${chalk.cyan(data.item.title || contentKey)}\n`);
+        }
+
+        const comments = data.comments || [];
+        if (comments.length === 0) {
+          console.log(chalk.dim('No comments.'));
+          return;
+        }
+
+        comments.forEach(c => {
+          const author = c.author?.username || c.author?.address?.slice(0, 10) || 'unknown';
+          const date = c.createdAt ? new Date(c.createdAt).toLocaleDateString() : '';
+          const edited = c.isEdited ? chalk.dim(' (edited)') : '';
+          console.log(`${chalk.cyan(author)} ${chalk.dim(date)}${edited}`);
+          console.log(`  ${c.text}`);
+          if (c.likes > 0) console.log(`  ${chalk.dim(`♥ ${c.likes}`)}`);
+          if (c.replyCount > 0) console.log(`  ${chalk.dim(`↳ ${c.replyCount} replies`)}`);
+          console.log('');
+        });
+
+        console.log(`${data.totalCount || comments.length} total comments`);
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+};

package/commands/config.js

@@ -0,0 +1,71 @@
+const chalk = require('chalk');
+const config = require('../lib/config');
+const output = require('../lib/output');
+
+module.exports = function (program) {
+  const cmd = program.command('config').description('Manage CLI configuration');
+
+  cmd
+    .command('set <key> <value>')
+    .description(`Set a config value. Keys: ${config.VALID_KEYS.join(', ')}`)
+    .action((key, value) => {
+      // Accept kebab-case and convert to camelCase
+      const keyMap = {
+        'api-key': 'apiKey',
+        'base-url': 'baseUrl',
+        'rpc-url': 'rpcUrl',
+        'admin-key': 'adminKey',
+        'wallet': 'wallet',
+      };
+      const resolved = keyMap[key] || key;
+
+      if (!config.VALID_KEYS.includes(resolved)) {
+        output.error(`Invalid key "${key}". Valid keys: ${config.VALID_KEYS.join(', ')}`);
+        process.exit(1);
+      }
+      config.set(resolved, value);
+      output.success(`Set ${resolved} = ${key === 'api-key' || key === 'apiKey' ? value.slice(0, 8) + '...' : value}`);
+    });
+
+  cmd
+    .command('get <key>')
+    .description('Get a config value')
+    .action((key) => {
+      const keyMap = {
+        'api-key': 'apiKey',
+        'base-url': 'baseUrl',
+        'rpc-url': 'rpcUrl',
+        'admin-key': 'adminKey',
+        'wallet': 'wallet',
+      };
+      const resolved = keyMap[key] || key;
+      const val = config.get(resolved);
+      if (output.isJsonMode()) {
+        output.json({ [resolved]: val || null });
+      } else {
+        console.log(val || chalk.dim('(not set)'));
+      }
+    });
+
+  cmd
+    .command('show')
+    .description('Show all config values')
+    .action(() => {
+      const cfg = config.load();
+      if (output.isJsonMode()) {
+        output.json(cfg);
+        return;
+      }
+      const masked = { ...cfg };
+      if (masked.apiKey) masked.apiKey = masked.apiKey.slice(0, 8) + '...';
+      if (masked.adminKey) masked.adminKey = masked.adminKey.slice(0, 8) + '...';
+      output.item(masked, [
+        ['API Key', 'apiKey'],
+        ['Base URL', 'baseUrl'],
+        ['Wallet', 'wallet'],
+        ['RPC URL', 'rpcUrl'],
+        ['Admin Key', 'adminKey'],
+      ]);
+      console.log(chalk.dim(`\nConfig file: ${config.CONFIG_FILE}`));
+    });
+};

package/commands/embeds.js

@@ -0,0 +1,120 @@
+const api = require('../lib/api');
+const output = require('../lib/output');
+
+module.exports = function (program) {
+  const cmd = program.command('embeds').description('Embed data API');
+
+  cmd
+    .command('card <address>')
+    .description('Get library card data for a member')
+    .action(async (address) => {
+      try {
+        const data = await api.get(`/embeds/card/${address}`, { auth: false });
+        if (output.isJsonMode()) {
+          output.json(data);
+          return;
+        }
+        if (!data.member) {
+          console.log('No member found for this address.');
+          return;
+        }
+        const m = data.member || {};
+        output.item(data, [
+          ['Display Name', 'displayName'],
+          ['Member ID', () => m.memberId],
+          ['ENS', () => m.ensSubname],
+          ['Joined', () => m.joinedAt ? new Date(m.joinedAt).toLocaleDateString() : null],
+          ['Uploads', () => `${data.uploads?.count || 0} (${((data.uploads?.totalBytes || 0) / 1024 / 1024).toFixed(2)} MB)`],
+          ['Stacks', 'stackCount'],
+          ['Grids', 'gridCount'],
+          ['Rank', 'rank'],
+          ['Storage Pass', () => m.hasUnlimitedStoragePass ? 'Yes' : 'No'],
+          ['ERC-8004', () => m.erc8004Verified ? (m.erc8004TokenId ? `Verified (#${m.erc8004TokenId})` : 'Verified') : 'No'],
+        ]);
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('grid <gridId>')
+    .description('Get grid embed data')
+    .action(async (gridId) => {
+      try {
+        const data = await api.get(`/embeds/grid/${gridId}`, { auth: false });
+        if (output.isJsonMode()) {
+          output.json(data);
+          return;
+        }
+        const g = data.grid || {};
+        output.item(g, [
+          ['Name', 'name'],
+          ['ID', 'id'],
+          ['Owner', 'owner'],
+          ['Columns', 'columns'],
+          ['Created', 'createdAt', v => v ? new Date(v).toLocaleString() : null],
+        ]);
+
+        if (data.cells && data.cells.length > 0) {
+          console.log('\nCells:');
+          output.table(
+            ['Pos', 'Title', 'Type', 'Key'],
+            data.cells.map(c => [
+              c.position,
+              c.title || '—',
+              c.mediaType || '—',
+              c.contentKey,
+            ])
+          );
+        }
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('user <address>')
+    .description('Get user profile embed data')
+    .option('-p, --page <n>', 'Page number', '1')
+    .option('-l, --limit <n>', 'Items per page (max 50)', '20')
+    .action(async (address, opts) => {
+      try {
+        const data = await api.get(`/embeds/user/${address}`, {
+          query: { page: opts.page, limit: opts.limit },
+          auth: false,
+        });
+        if (output.isJsonMode()) {
+          output.json(data);
+          return;
+        }
+        const m = data.member || {};
+        output.item(data, [
+          ['Display Name', 'displayName'],
+          ['Address', 'address'],
+          ['Member ID', () => m.memberId],
+          ['ENS', () => m.ensSubname],
+          ['Uploads', 'uploadCount'],
+          ['Total Size', 'totalBytes', v => v ? `${(v / 1024 / 1024).toFixed(2)} MB` : null],
+        ]);
+
+        if (data.uploads && data.uploads.length > 0) {
+          console.log('\nUploads:');
+          output.table(
+            ['Title', 'Type', 'Added', 'Key'],
+            data.uploads.map(u => [
+              u.title || '—',
+              u.mediaType || '—',
+              u.addedAt ? new Date(u.addedAt).toLocaleDateString() : '—',
+              u.contentKey,
+            ])
+          );
+          output.pagination(data.pagination);
+        }
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+};

package/commands/info.js

@@ -0,0 +1,57 @@
+const api = require('../lib/api');
+const output = require('../lib/output');
+
+module.exports = function (program) {
+  const cmd = program.command('info').description('API information');
+
+  cmd
+    .command('capabilities')
+    .description('View the API capabilities manifest')
+    .action(async () => {
+      try {
+        const data = await api.get('/capabilities', { auth: false });
+        if (output.isJsonMode()) {
+          output.json(data);
+          return;
+        }
+        output.item(data, [
+          ['Name', 'name'],
+          ['Version', 'version'],
+          ['URL', 'url'],
+          ['Chain', () => `${data.chain?.name} (${data.chain?.id})`],
+          ['CDN', 'cdn'],
+        ]);
+
+        if (data.pricing) {
+          console.log('\nPricing:');
+          output.table(
+            ['Item', 'Price'],
+            Object.entries(data.pricing)
+              .filter(([k]) => !['treasury', 'usdc', 'chain'].includes(k))
+              .map(([k, v]) => [k, v])
+          );
+        }
+
+        if (data.supportedMediaTypes) {
+          console.log(`\nMedia types: ${data.supportedMediaTypes.join(', ')}`);
+        }
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('skill')
+    .description('View the full agent skill document')
+    .action(async () => {
+      try {
+        const data = await api.get('/agent-skill', { auth: false });
+        // Agent skill is a large JSON doc — always output as JSON
+        output.json(data);
+      } catch (err) {
+        output.error(err.message);
+        process.exit(1);
+      }
+    });
+};