@builtwith/sdk 1.2.0 → 1.4.0

package/README.md

@@ -60,6 +60,9 @@ if (result.ok) {
 | `financial({ lookup })` | Root domain | Financial data |
 | `social({ lookup })` | Root domain | Social profile related domains |
 | `vector_search({ query, limit? })` | Search query | Semantic technology/category search |
+| `payment_discovery()` | — | Agent Payment API: credit balance |
+| `payment_configuration()` | — | Agent Payment API: spending limits |
+| `payment_purchase({ credits })` | Integer ≥ 2000 | Agent Payment API: purchase credits |
 
 ### Response Format
 
@@ -126,6 +129,9 @@ All methods accept a `CancellationToken` as an optional last parameter.
 | `financial(lookup)` | `string` | Financial data |
 | `social(lookup)` | `string` | Social profile related domains |
 | `vector_search(query, limit?)` | `string`, `int?` | Semantic technology/category search |
+| `payment_discovery()` | — | Agent Payment API: credit balance |
+| `payment_configuration()` | — | Agent Payment API: spending limits |
+| `payment_purchase(credits)` | `int` ≥ 2000 | Agent Payment API: purchase credits |
 
 ### Response Format
 
@@ -148,6 +154,23 @@ BUILTWITH_API_KEY=your-key dotnet run
 
 ---
 
+## Agent Payment API
+
+The payment methods let AI agents check credit balances, view spending configuration, and purchase credits. They route through the standard MCP endpoint using your existing API key. Configure billing at [payments.builtwith.com/agent-payment-api-config](https://payments.builtwith.com/agent-payment-api-config).
+
+```js
+// Node.js
+const result = await client.payment_discovery();
+// result.data => { credits_total, credits_used, credits_available }
+```
+
+```csharp
+// C#
+var result = await client.payment_discovery();
+```
+
+---
+
 ## Prompt Helpers
 
 Both SDKs include prompt helper methods for use with AI agents:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builtwith/sdk",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "BuiltWith AI-first SDK for Node.js",
   "main": "src/index.js",
   "exports": {

package/src/index.js

@@ -7,7 +7,6 @@ const { URL } = require('url');
 // ── Constants ──────────────────────────────────────────────────────────────────
 
 const MCP_ENDPOINT = 'https://api.builtwith.com/mcp';
-const PAYMENTS_ENDPOINT = 'https://payments.builtwith.com';
 const MAX_RETRIES = 3;
 const INITIAL_BACKOFF_MS = 1000;
 const DOMAIN_RE = /^(?!-)[a-zA-Z0-9-]{1,63}(?<!-)(\.[a-zA-Z]{2,})+$/;
@@ -134,37 +133,6 @@ function _http_post(url_str, body, headers, timeout_ms) {
   });
 }
 
-function _http_get(url_str, headers, timeout_ms) {
-  return new Promise((resolve, reject) => {
-    const parsed = new URL(url_str);
-    const transport = parsed.protocol === 'http:' ? http : https;
-    const opts = {
-      hostname: parsed.hostname,
-      port: parsed.port || (parsed.protocol === 'http:' ? 80 : 443),
-      path: parsed.pathname + parsed.search,
-      method: 'GET',
-      headers: {
-        ...headers,
-        'Accept': 'application/json',
-      },
-      timeout: timeout_ms,
-    };
-
-    const req = transport.request(opts, (res) => {
-      const chunks = [];
-      res.on('data', chunk => chunks.push(chunk));
-      res.on('end', () => {
-        const raw_body = Buffer.concat(chunks).toString('utf-8');
-        resolve({ status: res.statusCode, headers: res.headers, body: raw_body });
-      });
-    });
-
-    req.on('error', reject);
-    req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
-    req.end();
-  });
-}
-
 // ── Client ─────────────────────────────────────────────────────────────────────
 
 class BuiltWithClient {
@@ -174,7 +142,6 @@ class BuiltWithClient {
     }
     this._api_key = api_key;
     this._endpoint = options.endpoint || MCP_ENDPOINT;
-    this._payments_endpoint = options.payments_endpoint || PAYMENTS_ENDPOINT;
     this._max_retries = options.max_retries != null ? options.max_retries : MAX_RETRIES;
     this._timeout_ms = options.timeout_ms || 30000;
   }
@@ -271,38 +238,6 @@ class BuiltWithClient {
     return _err(last_error || new BuiltWithError('UNKNOWN_ERROR', 'Request failed', 0), mcp_tool);
   }
 
-  // ── Payment API ────────────────────────────────────────────────────────────
-
-  async _payment_request(method, path, body = null) {
-    const url = this._payments_endpoint + path;
-    const headers = { Authorization: `Bearer ${this._api_key}` };
-    try {
-      const res = method === 'GET'
-        ? await _http_get(url, headers, this._timeout_ms)
-        : await _http_post(url, body, headers, this._timeout_ms);
-
-      const status = res.status;
-
-      if (status === 400) return _err(new BuiltWithError('VALIDATION_ERROR', `HTTP 400: ${res.body.substring(0, 200)}`, status, null, 'Check request parameters.'), path);
-      if (status === 401 || status === 403) return _err(new BuiltWithError('AUTH_ERROR', 'Authentication failed. Check your API key.', status, null, 'Verify your BuiltWith API key is correct and active.'), path);
-      if (status === 402) return _err(new BuiltWithError('PAYMENT_FAILED', `HTTP 402: ${res.body.substring(0, 200)}`, status, null, 'Payment could not be processed. Check your billing details at payments.builtwith.com/agent-payment-api-config.'), path);
-      if (status === 405) return _err(new BuiltWithError('METHOD_NOT_ALLOWED', `HTTP 405: wrong HTTP method.`, status), path);
-      if (status >= 500) return _err(new BuiltWithError('SERVER_ERROR', `HTTP ${status}: ${res.body.substring(0, 200)}`, status, null, 'The server encountered an error. Try again later.'), path);
-      if (status < 200 || status >= 300) return _err(new BuiltWithError('HTTP_ERROR', `HTTP ${status}: ${res.body.substring(0, 200)}`, status), path);
-
-      let parsed;
-      try {
-        parsed = JSON.parse(res.body);
-      } catch (_) {
-        return _err(new BuiltWithError('PARSE_ERROR', 'Failed to parse response JSON.', status), path);
-      }
-
-      return _ok(parsed, parsed, path);
-    } catch (err) {
-      return _err(new BuiltWithError('NETWORK_ERROR', err.message, 0, null, 'Check network connectivity.'), path);
-    }
-  }
-
   // ── Public SDK methods ─────────────────────────────────────────────────────
 
   async domain_lookup_live(params) {
@@ -395,12 +330,22 @@ class BuiltWithClient {
     return this._request('vector-search', { query, ...(limit != null ? { limit } : {}) });
   }
 
+  async keyword_search(params) {
+    const { keyword, limit, offset } = params || {};
+    _validate_string('keyword', keyword);
+    return this._request('keyword-search-api', {
+      keyword,
+      ...(limit != null ? { limit } : {}),
+      ...(offset != null ? { offset } : {}),
+    });
+  }
+
   async payment_discovery() {
-    return this._payment_request('GET', '/v1/billing/api-discovery');
+    return this._request('payment-balance', {});
   }
 
   async payment_configuration() {
-    return this._payment_request('GET', '/v1/billing/api-configuration');
+    return this._request('payment-config', {});
   }
 
   async payment_purchase(params) {
@@ -414,7 +359,7 @@ class BuiltWithClient {
     if (credits < 2000) {
       throw new BuiltWithError('VALIDATION_ERROR', 'credits must be at least 2000.', 0, null, 'Minimum purchase is 2000 credits.');
     }
-    return this._payment_request('POST', '/v1/billing/api-purchase', { credits });
+    return this._request('payment-purchase', { credits });
   }
 
   // ── Prompt helpers ─────────────────────────────────────────────────────────
@@ -448,6 +393,41 @@ class BuiltWithClient {
     _validate_domain(domain);
     return { mcp_prompt: 'check-domain-trust', arguments: { domain } };
   }
+
+  // ── Agent Device-Code Authorization (no API key required) ─────────────────
+
+  static async agent_auth_start() {
+    try {
+      const res = await _http_post('https://api.builtwith.com/agent-auth/start', {}, {}, 30000);
+      if (res.status < 200 || res.status >= 300) {
+        return _err(new BuiltWithError('HTTP_ERROR', `HTTP ${res.status}: ${res.body.substring(0, 200)}`, res.status), 'agent-auth-start');
+      }
+      let data;
+      try { data = JSON.parse(res.body); } catch (_) {
+        return _err(new BuiltWithError('PARSE_ERROR', 'Failed to parse agent-auth-start response.', res.status), 'agent-auth-start');
+      }
+      return _ok(data, data, 'agent-auth-start');
+    } catch (err) {
+      return _err(new BuiltWithError('NETWORK_ERROR', err.message, 0, null, 'Check network connectivity.'), 'agent-auth-start');
+    }
+  }
+
+  static async agent_auth_token(device_code) {
+    _validate_string('device_code', device_code);
+    try {
+      const res = await _http_post('https://api.builtwith.com/agent-auth/token', { device_code }, {}, 30000);
+      if (res.status < 200 || res.status >= 300) {
+        return _err(new BuiltWithError('HTTP_ERROR', `HTTP ${res.status}: ${res.body.substring(0, 200)}`, res.status), 'agent-auth-token');
+      }
+      let data;
+      try { data = JSON.parse(res.body); } catch (_) {
+        return _err(new BuiltWithError('PARSE_ERROR', 'Failed to parse agent-auth-token response.', res.status), 'agent-auth-token');
+      }
+      return _ok(data, data, 'agent-auth-token');
+    } catch (err) {
+      return _err(new BuiltWithError('NETWORK_ERROR', err.message, 0, null, 'Check network connectivity.'), 'agent-auth-token');
+    }
+  }
 }
 
 module.exports = { BuiltWithClient, BuiltWithError };