builtwith-official-cli 1.0.0

package/lib/config.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { ConfigError } = require('./errors');
+
+// Load .env silently from CWD
+try {
+  require('dotenv').config({ path: path.join(process.cwd(), '.env'), quiet: true });
+} catch (_) {}
+
+function loadRcFile(dir) {
+  const rcPath = path.join(dir, '.builtwithrc');
+  try {
+    const raw = fs.readFileSync(rcPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.key || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Resolve API key using priority order:
+ * 1. --key CLI flag
+ * 2. BUILTWITH_API_KEY env var
+ * 3. .builtwithrc in CWD
+ * 4. .builtwithrc in home dir
+ */
+function resolveKey(flagValue) {
+  if (flagValue) return flagValue;
+  if (process.env.BUILTWITH_API_KEY) return process.env.BUILTWITH_API_KEY;
+  const cwdKey = loadRcFile(process.cwd());
+  if (cwdKey) return cwdKey;
+  const homeKey = loadRcFile(os.homedir());
+  if (homeKey) return homeKey;
+  return null;
+}
+
+function requireKey(flagValue) {
+  const key = resolveKey(flagValue);
+  if (!key) {
+    throw new ConfigError(
+      'No API key found. Provide via --key, BUILTWITH_API_KEY env var, or .builtwithrc file.'
+    );
+  }
+  return key;
+}
+
+module.exports = { resolveKey, requireKey };

package/lib/errors.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const EXIT_CODES = {
+  SUCCESS: 0,
+  UNEXPECTED: 1,
+  AUTH: 2,
+  NOT_FOUND: 3,
+  RATE_LIMIT: 4,
+  API_ERROR: 5,
+  NETWORK: 6,
+  INVALID_INPUT: 7,
+  INTERRUPTED: 8,
+};
+
+class BuiltWithError extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.name = this.constructor.name;
+    this.exitCode = exitCode;
+  }
+}
+
+class InputError extends BuiltWithError {
+  constructor(message) {
+    super(message, EXIT_CODES.INVALID_INPUT);
+  }
+}
+
+class ConfigError extends BuiltWithError {
+  constructor(message) {
+    super(message, EXIT_CODES.AUTH);
+  }
+}
+
+class ApiError extends BuiltWithError {
+  constructor(message, statusCode) {
+    let exitCode = EXIT_CODES.API_ERROR;
+    if (statusCode === 401 || statusCode === 403) exitCode = EXIT_CODES.AUTH;
+    else if (statusCode === 404) exitCode = EXIT_CODES.NOT_FOUND;
+    else if (statusCode === 429) exitCode = EXIT_CODES.RATE_LIMIT;
+    super(message, exitCode);
+    this.statusCode = statusCode;
+  }
+}
+
+class NetworkError extends BuiltWithError {
+  constructor(message) {
+    super(message, EXIT_CODES.NETWORK);
+  }
+}
+
+module.exports = { EXIT_CODES, BuiltWithError, InputError, ConfigError, ApiError, NetworkError };

package/lib/output.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const Table = require('cli-table3');
+const { stringify } = require('csv-stringify/sync');
+const chalk = require('chalk');
+
+let noColor = false;
+
+function setNoColor(val) {
+  noColor = val;
+  if (val) chalk.level = 0;
+}
+
+/**
+ * Flatten a nested object into dot-notation key/value pairs (one level deep for tables).
+ */
+function flattenOne(obj, prefix = '') {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      out[key] = JSON.stringify(v);
+    } else if (Array.isArray(v)) {
+      out[key] = JSON.stringify(v);
+    } else {
+      out[key] = v;
+    }
+  }
+  return out;
+}
+
+function toRows(data) {
+  if (Array.isArray(data)) return data.map(item =>
+    typeof item === 'object' && item !== null ? flattenOne(item) : { value: item }
+  );
+  if (typeof data === 'object' && data !== null) return [flattenOne(data)];
+  return [{ value: data }];
+}
+
+function printJson(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+
+function printTable(data) {
+  const rows = toRows(data);
+  if (rows.length === 0) {
+    process.stdout.write('(no results)\n');
+    return;
+  }
+  const headers = Object.keys(rows[0]);
+  const table = new Table({ head: headers });
+  for (const row of rows) {
+    table.push(headers.map(h => {
+      const v = row[h];
+      return v === null || v === undefined ? '' : String(v);
+    }));
+  }
+  process.stdout.write(table.toString() + '\n');
+}
+
+function printCsv(data) {
+  const rows = toRows(data);
+  if (rows.length === 0) {
+    process.stdout.write('\n');
+    return;
+  }
+  const headers = Object.keys(rows[0]);
+  const output = stringify(
+    rows.map(r => headers.map(h => {
+      const v = r[h];
+      return v === null || v === undefined ? '' : String(v);
+    })),
+    { header: true, columns: headers }
+  );
+  process.stdout.write(output);
+}
+
+function print(data, opts = {}) {
+  const fmt = (opts.format || 'json').toLowerCase();
+  if (fmt === 'table') return printTable(data);
+  if (fmt === 'csv') return printCsv(data);
+  return printJson(data);
+}
+
+function error(msg) {
+  const prefix = noColor ? '[error]' : chalk.red('[error]');
+  process.stderr.write(`${prefix} ${msg}\n`);
+}
+
+function warn(msg) {
+  const prefix = noColor ? '[warn]' : chalk.yellow('[warn]');
+  process.stderr.write(`${prefix} ${msg}\n`);
+}
+
+function info(msg) {
+  const prefix = noColor ? '[info]' : chalk.cyan('[info]');
+  process.stderr.write(`${prefix} ${msg}\n`);
+}
+
+module.exports = { print, error, warn, info, setNoColor };

package/lib/ws-client.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const WebSocket = require('ws');
+const { NetworkError } = require('./errors');
+
+const WS_URL = 'wss://sync.builtwith.com';
+
+/**
+ * Connect to the BuiltWith live feed WebSocket.
+ * @param {string} key - API key
+ * @param {object} opts - { onMessage, onError, onClose, debug }
+ * @returns {{ close: Function }} - Object with close() to disconnect
+ */
+function connect(key, opts = {}) {
+  const { onMessage, onError, onClose, debug } = opts;
+
+  const url = `${WS_URL}?KEY=${encodeURIComponent(key)}`;
+  if (debug) process.stderr.write(`[debug] WS connect: ${WS_URL}?KEY=REDACTED\n`);
+
+  const ws = new WebSocket(url);
+
+  ws.on('open', () => {
+    if (debug) process.stderr.write('[debug] WS connection opened\n');
+  });
+
+  ws.on('message', (data) => {
+    try {
+      const parsed = JSON.parse(data.toString());
+      if (onMessage) onMessage(parsed);
+    } catch (_) {
+      // Pass raw data if not JSON
+      if (onMessage) onMessage({ raw: data.toString() });
+    }
+  });
+
+  ws.on('error', (err) => {
+    if (debug) process.stderr.write(`[debug] WS error: ${err.message}\n`);
+    if (onError) onError(new NetworkError(`WebSocket error: ${err.message}`));
+  });
+
+  ws.on('close', (code, reason) => {
+    if (debug) process.stderr.write(`[debug] WS closed: ${code} ${reason}\n`);
+    if (onClose) onClose(code, reason);
+  });
+
+  return {
+    close() {
+      ws.close();
+    },
+  };
+}
+
+module.exports = { connect };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "builtwith-official-cli",
+  "version": "1.0.0",
+  "description": "Non-interactive, scriptable CLI for the BuiltWith API",
+  "main": "lib/cli.js",
+  "bin": {
+    "bw": "bin/bw.js",
+    "builtwith": "bin/bw.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "keywords": ["builtwith", "cli", "api"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/builtwith/builtwith-official-cli.git"
+  },
+  "homepage": "https://github.com/builtwith/builtwith-official-cli#readme",
+  "bugs": {
+    "url": "https://github.com/builtwith/builtwith-official-cli/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "csv-stringify": "^6.6.0",
+    "dotenv": "^17.3.1",
+    "node-fetch": "^2.7.0",
+    "ora": "^5.4.1",
+    "ws": "^8.19.0"
+  }
+}