@builtwith/sdk 1.3.0 → 1.4.1

package/README.md

@@ -63,6 +63,8 @@ if (result.ok) {
 | `payment_discovery()` | — | Agent Payment API: credit balance |
 | `payment_configuration()` | — | Agent Payment API: spending limits |
 | `payment_purchase({ credits })` | Integer ≥ 2000 | Agent Payment API: purchase credits |
+| `BuiltWithClient.agent_auth_start()` | — | Start Device-Code Authorization (static, no key required) |
+| `BuiltWithClient.agent_auth_token(device_code)` | Device code string | Poll for auth result and access token (static, no key required) |
 
 ### Response Format
 
@@ -132,6 +134,8 @@ All methods accept a `CancellationToken` as an optional last parameter.
 | `payment_discovery()` | — | Agent Payment API: credit balance |
 | `payment_configuration()` | — | Agent Payment API: spending limits |
 | `payment_purchase(credits)` | `int` ≥ 2000 | Agent Payment API: purchase credits |
+| `BuiltWithClient.agent_auth_start()` | — | Start Device-Code Authorization (static, no key required) |
+| `BuiltWithClient.agent_auth_token(deviceCode)` | `string` | Poll for auth result and access token (static, no key required) |
 
 ### Response Format
 
@@ -154,6 +158,41 @@ BUILTWITH_API_KEY=your-key dotnet run
 
 ---
 
+## Agent Device-Code Authorization
+
+Agents can obtain a temporary `bw-` prefixed API token without the user pasting their key. These are **static methods** — no API key or client instance required.
+
+```js
+// Node.js
+const { BuiltWithClient } = require('@builtwith/sdk');
+
+// Step 1: start the flow
+const start = await BuiltWithClient.agent_auth_start();
+// start.data => { device_code, verification_uri }
+
+console.log(`Open in browser: ${start.data.verification_uri}`);
+
+// Step 2: poll every 5 seconds
+const token = await BuiltWithClient.agent_auth_token(start.data.device_code);
+// token.data => { status: 'pending' | 'approved' | 'denied', access_token? }
+
+if (token.data.status === 'approved') {
+  const client = new BuiltWithClient(token.data.access_token);
+  // use client normally
+}
+```
+
+```csharp
+// C#
+var start = await BuiltWithClient.agent_auth_start();
+// start.Data => { device_code, verification_uri }
+
+var token = await BuiltWithClient.agent_auth_token(deviceCode);
+// token.Data => { status, access_token }
+```
+
+---
+
 ## 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).

package/package.json

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

package/src/index.js

@@ -393,6 +393,39 @@ 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);
+      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');
+      }
+      // Pass through body even on 4xx — error field carries meaningful status (access_denied, expired_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 };