builtwith-official-cli 1.1.0 → 1.5.0

package/README.md

@@ -170,6 +170,32 @@ bw products search "running shoes" --page 2 --limit 50
 bw trust lookup <domain>
 ```
 
+### 🔎 Vector Search
+
+```bash
+bw vector search <query> [--limit <n>]
+```
+
+```bash
+bw vector search "react framework"
+bw vector search "ecommerce platform" --limit 20
+```
+
+### 💳 Payment
+
+Manage API credits autonomously.
+
+```bash
+bw payment balance           # current credit balance
+bw payment config            # limits, pricing, monthly usage
+bw payment purchase <credits> # purchase credits (minimum 2000)
+```
+
+```bash
+bw payment balance
+bw payment purchase 2000
+```
+
 ### 👤 Account
 
 ```bash
@@ -359,6 +385,10 @@ If your API key isn't in an env var or `.builtwithrc`, pass it inline:
 | `trends_tech` | 📈 Historical adoption trend for a technology |
 | `products_search` | 🛍️ Search ecommerce products across indexed stores |
 | `trust_lookup` | 🛡️ Trust/quality score for a domain |
+| `vector_search` | 🔎 Semantic search across technologies and categories |
+| `payment_balance` | 💳 Get current Agent Payment API credit balance |
+| `payment_config` | ⚙️ Retrieve payment limits and pricing configuration |
+| `payment_purchase` | 🛒 Purchase API credits (minimum 2000) |
 | `account_whoami` | 👤 Authenticated account identity |
 | `account_usage` | 📊 API usage statistics |
 

package/lib/cli.js

@@ -35,10 +35,14 @@ function run() {
   require('./commands/trends')(program);
   require('./commands/products')(program);
   require('./commands/trust')(program);
+  require('./commands/vector')(program);
+  require('./commands/keyword-search')(program);
+  require('./commands/payment')(program);
   require('./commands/account')(program);
   require('./commands/live')(program);
   require('./commands/mcp')(program);
   require('./commands/schema')(program);
+  require('./commands/auth')(program);
 
   program.parseAsync(process.argv).catch(err => {
     if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {

package/lib/client.js

@@ -36,8 +36,15 @@ const BASE_URLS = {
   trends:          'https://api.builtwith.com/trends/v6/api.json',
   products:        'https://api.builtwith.com/productv1/api.json',
   trust:           'https://api.builtwith.com/trustv1/api.json',
+  vector:          'https://api.builtwith.com/vector/v1/api.json',
+  'keyword-search': 'https://api.builtwith.com/kws1/api.json',
   whoami:          'https://api.builtwith.com/whoamiv1/api.json',
   usage:           'https://api.builtwith.com/usagev2/api.json',
+  'payment-balance': 'https://payments.builtwith.com/v1/billing/api-discovery',
+  'payment-config':  'https://payments.builtwith.com/v1/billing/api-configuration',
+  'payment-purchase': 'https://payments.builtwith.com/v1/billing/api-purchase',
+  'agent-auth-start': 'https://api.builtwith.com/agent-auth/start',
+  'agent-auth-token': 'https://api.builtwith.com/agent-auth/token',
 };
 
 /**
@@ -61,7 +68,7 @@ function maskKey(url, key) {
 }
 
 async function request(endpoint, params, opts = {}) {
-  const { dryRun, debug, spinner } = opts;
+  const { dryRun, debug, spinner, method = 'GET', body } = opts;
   const url = buildUrl(endpoint, params);
 
   if (dryRun) {
@@ -71,17 +78,24 @@ async function request(endpoint, params, opts = {}) {
   }
 
   if (debug) {
-    process.stderr.write(`[debug] GET ${maskKey(url, params.KEY || params.key)}\n`);
+    process.stderr.write(`[debug] ${method} ${maskKey(url, params.KEY || params.key)}\n`);
   }
 
   if (spinner) spinner.start();
 
+  const fetchOpts = {
+    method,
+    headers: { 'User-Agent': 'builtwith-cli/1.0.0' },
+    timeout: 30000,
+  };
+  if (body !== undefined) {
+    fetchOpts.body = JSON.stringify(body);
+    fetchOpts.headers['Content-Type'] = 'application/json';
+  }
+
   let res;
   try {
-    res = await fetch(url, {
-      headers: { 'User-Agent': 'builtwith-cli/1.0.0' },
-      timeout: 30000,
-    });
+    res = await fetch(url, fetchOpts);
   } catch (err) {
     if (spinner) spinner.stop();
     throw new NetworkError(`Network request failed: ${err.message}`);
@@ -93,30 +107,30 @@ async function request(endpoint, params, opts = {}) {
 
   if (spinner) spinner.stop();
 
-  let body;
+  let resBody;
   try {
-    body = await res.json();
+    resBody = await res.json();
   } catch (_) {
     throw new ApiError(`Invalid JSON response (HTTP ${res.status})`, res.status);
   }
 
   if (!res.ok) {
-    const msg = body && body.Errors
-      ? body.Errors.map(e => e.Message || e).join('; ')
+    const msg = resBody && resBody.Errors
+      ? resBody.Errors.map(e => e.Message || e).join('; ')
       : `HTTP ${res.status} ${res.statusText}`;
     throw new ApiError(msg, res.status);
   }
 
   // BuiltWith API sometimes returns error info in the body with HTTP 200
-  if (body && body.Errors && body.Errors.length > 0) {
-    const msg = body.Errors.map(e => e.Message || e).join('; ');
+  if (resBody && resBody.Errors && resBody.Errors.length > 0) {
+    const msg = resBody.Errors.map(e => e.Message || e).join('; ');
     // Treat auth-related messages as auth errors
     const isAuth = /key|auth|unauthori/i.test(msg);
     throw new ApiError(msg, isAuth ? 403 : 400);
   }
 
-  scanForInjection(body);
-  return body;
+  scanForInjection(resBody);
+  return resBody;
 }
 
 module.exports = { buildUrl, maskKey, request, scanForInjection, BASE_URLS };

package/lib/commands/auth.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const fetch = require('node-fetch');
+const output = require('../output');
+
+const AUTH_START_URL = 'https://api.builtwith.com/agent-auth/start';
+const AUTH_TOKEN_URL = 'https://api.builtwith.com/agent-auth/token';
+const POLL_INTERVAL_MS = 5000;
+const TIMEOUT_MS = 5 * 60 * 1000;
+
+module.exports = function registerAuth(program) {
+  const auth = program.command('auth').description('Agent Device-Code Authorization – obtain a temporary API token');
+
+  auth
+    .command('login')
+    .description('Authorize this agent to use the BuiltWith API via browser approval')
+    .action(async () => {
+      const opts = program.opts();
+      if (opts.noColor) output.setNoColor(true);
+
+      // Step 1: start the device-code flow
+      let startRes;
+      try {
+        const res = await fetch(AUTH_START_URL, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: '{}',
+        });
+        startRes = await res.json();
+      } catch (err) {
+        output.error(`Failed to start authorization: ${err.message}`);
+        process.exit(1);
+      }
+
+      const { device_code, verification_uri } = startRes;
+      if (!device_code || !verification_uri) {
+        output.error('Unexpected response from authorization server.');
+        process.exit(1);
+      }
+
+      // Step 2: prompt user to open the browser
+      process.stderr.write(`\nOpen this URL in your browser to authorize access:\n\n  ${verification_uri}\n\nWaiting for approval`);
+
+      // Step 3: poll every 5 seconds
+      const deadline = Date.now() + TIMEOUT_MS;
+      while (Date.now() < deadline) {
+        await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+        process.stderr.write('.');
+
+        let tokenRes;
+        try {
+          const res = await fetch(AUTH_TOKEN_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ device_code }),
+          });
+          tokenRes = await res.json();
+        } catch (err) {
+          output.error(`\nPolling error: ${err.message}`);
+          process.exit(1);
+        }
+
+        if (tokenRes.status === 'approved' && tokenRes.access_token) {
+          process.stderr.write('\n\n');
+          output.print({ access_token: tokenRes.access_token, message: 'Authorization approved. Use this token as your BW_API_KEY.' }, { format: opts.format });
+          return;
+        }
+
+        if (tokenRes.status === 'denied') {
+          process.stderr.write('\n');
+          output.error('Authorization was denied by the user.');
+          process.exit(1);
+        }
+        // status === 'pending' — keep polling
+      }
+
+      process.stderr.write('\n');
+      output.error('Authorization timed out after 5 minutes.');
+      process.exit(1);
+    });
+};

package/lib/commands/keyword-search.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { requireKey } = require('../config');
+const { request } = require('../client');
+const output = require('../output');
+const ora = require('ora');
+
+module.exports = function registerKeywordSearch(program) {
+  const kws = program.command('keyword-search').description('Find websites containing a specific keyword');
+
+  kws
+    .command('search <keyword>')
+    .description('Search for websites by keyword')
+    .option('--limit <n>', 'Results per page (16-1000)', parseInt)
+    .option('--offset <offset>', 'Pagination offset (NextOffset from previous response)')
+    .action(async (keywordArg, cmdOpts) => {
+      const opts = program.opts();
+      if (opts.noColor) output.setNoColor(true);
+      const key = requireKey(opts.key);
+      const params = { KEY: key, KEYWORD: keywordArg };
+      if (cmdOpts.limit) params.LIMIT = cmdOpts.limit;
+      if (cmdOpts.offset) params.OFFSET = cmdOpts.offset;
+      const spinner = opts.quiet ? null : ora({ text: `Searching for "${keywordArg}"...`, stream: process.stderr }).start();
+      try {
+        const data = await request('keyword-search', params, { dryRun: opts.dryRun, debug: opts.debug, spinner });
+        output.print(data, { format: opts.format });
+      } catch (err) {
+        if (spinner) spinner.stop();
+        throw err;
+      }
+    });
+};

package/lib/commands/payment.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const { requireKey } = require('../config');
+const { request } = require('../client');
+const { InputError } = require('../errors');
+const output = require('../output');
+const ora = require('ora');
+
+module.exports = function registerPayment(program) {
+  const payment = program.command('payment').description('Agent Payment API – manage and purchase API credits');
+
+  payment
+    .command('balance')
+    .description('Get current credit balance')
+    .action(async () => {
+      const opts = program.opts();
+      if (opts.noColor) output.setNoColor(true);
+      const key = requireKey(opts.key);
+      const params = { KEY: key };
+      const spinner = opts.quiet ? null : ora({ text: 'Fetching credit balance...', stream: process.stderr }).start();
+      try {
+        const data = await request('payment-balance', params, { dryRun: opts.dryRun, debug: opts.debug, spinner });
+        output.print(data, { format: opts.format, fields: opts.fields });
+      } catch (err) {
+        if (spinner) spinner.stop();
+        throw err;
+      }
+    });
+
+  payment
+    .command('config')
+    .description('Retrieve payment configuration (limits, pricing)')
+    .action(async () => {
+      const opts = program.opts();
+      if (opts.noColor) output.setNoColor(true);
+      const key = requireKey(opts.key);
+      const params = { KEY: key };
+      const spinner = opts.quiet ? null : ora({ text: 'Fetching payment config...', stream: process.stderr }).start();
+      try {
+        const data = await request('payment-config', params, { dryRun: opts.dryRun, debug: opts.debug, spinner });
+        output.print(data, { format: opts.format, fields: opts.fields });
+      } catch (err) {
+        if (spinner) spinner.stop();
+        throw err;
+      }
+    });
+
+  payment
+    .command('purchase <credits>')
+    .description('Purchase API credits (minimum 2000)')
+    .action(async (creditsArg) => {
+      const opts = program.opts();
+      if (opts.noColor) output.setNoColor(true);
+      const key = requireKey(opts.key);
+      const credits = parseInt(creditsArg, 10);
+      if (isNaN(credits) || credits < 2000) throw new InputError('credits must be an integer of at least 2000');
+      const params = { KEY: key };
+      const spinner = opts.quiet ? null : ora({ text: `Purchasing ${credits} credits...`, stream: process.stderr }).start();
+      try {
+        const data = await request('payment-purchase', params, { dryRun: opts.dryRun, debug: opts.debug, spinner, method: 'POST', body: { credits } });
+        output.print(data, { format: opts.format, fields: opts.fields });
+      } catch (err) {
+        if (spinner) spinner.stop();
+        throw err;
+      }
+    });
+};

package/lib/commands/vector.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const { requireKey } = require('../config');
+const { request } = require('../client');
+const output = require('../output');
+const ora = require('ora');
+
+module.exports = function registerVector(program) {
+  const vector = program.command('vector').description('Vector search for technologies and categories');
+
+  vector
+    .command('search <query>')
+    .description('Search technologies and categories by text using semantic similarity')
+    .option('--limit <n>', 'Number of results (default 10, max 100)', parseInt)
+    .action(async (queryArg, cmdOpts) => {
+      const opts = program.opts();
+      if (opts.noColor) output.setNoColor(true);
+      const key = requireKey(opts.key);
+      const params = { KEY: key, QUERY: queryArg };
+      if (cmdOpts.limit) params.LIMIT = cmdOpts.limit;
+      const spinner = opts.quiet ? null : ora({ text: `Searching for "${queryArg}"...`, stream: process.stderr }).start();
+      try {
+        const data = await request('vector', params, { dryRun: opts.dryRun, debug: opts.debug, spinner });
+        output.print(data, { format: opts.format });
+      } catch (err) {
+        if (spinner) spinner.stop();
+        throw err;
+      }
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "builtwith-official-cli",
-  "version": "1.1.0",
+  "version": "1.5.0",
   "description": "Non-interactive, scriptable CLI for the BuiltWith API",
   "main": "lib/cli.js",
   "bin": {