@web-agent-proxy/sdk-js 1.0.0

package/dist/crypto-helper.d.ts

@@ -0,0 +1,9 @@
+export declare function deriveKey(passphrase: string): Buffer;
+export interface EncryptedPayload {
+    iv: string;
+    tag: string;
+    data: string;
+}
+export declare function encryptPayload(plaintext: string, key: Buffer): EncryptedPayload;
+export declare function decryptPayload(ciphertext: string, key: Buffer, ivBase64: string, tagBase64: string): string;
+//# sourceMappingURL=crypto-helper.d.ts.map

package/dist/crypto-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-helper.d.ts","sourceRoot":"","sources":["../src/crypto-helper.ts"],"names":[],"mappings":"AAEA,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAc/E;AAED,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAWR"}

package/dist/crypto-helper.js

@@ -0,0 +1,26 @@
+import crypto from "crypto";
+export function deriveKey(passphrase) {
+    return crypto.createHash("sha256").update(passphrase).digest();
+}
+export function encryptPayload(plaintext, key) {
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    let encrypted = cipher.update(plaintext, "utf8", "base64");
+    encrypted += cipher.final("base64");
+    const tag = cipher.getAuthTag().toString("base64");
+    return {
+        iv: iv.toString("base64"),
+        tag: tag,
+        data: encrypted,
+    };
+}
+export function decryptPayload(ciphertext, key, ivBase64, tagBase64) {
+    const iv = Buffer.from(ivBase64, "base64");
+    const tag = Buffer.from(tagBase64, "base64");
+    const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    let decrypted = decipher.update(ciphertext, "base64", "utf8");
+    decrypted += decipher.final("utf8");
+    return decrypted;
+}
+//# sourceMappingURL=crypto-helper.js.map

package/dist/crypto-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-helper.js","sourceRoot":"","sources":["../src/crypto-helper.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,MAAM,UAAU,SAAS,CAAC,UAAkB;IAC1C,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,CAAC;AACjE,CAAC;AAQD,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,GAAW;IAC3D,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAE7D,IAAI,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC3D,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAEpC,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEnD,OAAO;QACL,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACzB,GAAG,EAAE,GAAG;QACR,IAAI,EAAE,SAAS;KAChB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,UAAkB,EAClB,GAAW,EACX,QAAgB,EAChB,SAAiB;IAEjB,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAE7C,MAAM,QAAQ,GAAG,MAAM,CAAC,gBAAgB,CAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACjE,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAEzB,IAAI,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9D,SAAS,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAEpC,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+export interface ProxyRequestOptions {
+    action?: "scrape" | "screenshot";
+    method?: string;
+    headers?: Record<string, string>;
+    cookies?: any[];
+}
+export interface ProxyResponse {
+    status: number;
+    headers: Record<string, string>;
+    content?: string;
+    screenshot?: string;
+    cookies?: any[];
+}
+export interface BrowserClientInfo {
+    id: string;
+    metadata: {
+        name: string;
+        platform: string;
+    };
+    status: "idle" | "busy";
+}
+export declare class WebAgentProxyClient {
+    private bridgeUrl;
+    private defaultClientId?;
+    private encryptionKey?;
+    private apiKey?;
+    constructor(options?: {
+        bridgeUrl?: string;
+        defaultClientId?: string;
+        encryptionKey?: string;
+        apiKey?: string;
+    });
+    private getAuthHeaders;
+    /**
+     * Retrieves a list of all active browser clients connected to the bridge.
+     */
+    getBrowsers(): Promise<BrowserClientInfo[]>;
+    /**
+     * Routes a web request through a registered browser client.
+     */
+    request(url: string, options?: ProxyRequestOptions & {
+        clientId?: string;
+    }): Promise<ProxyResponse>;
+    /**
+     * Helper method to scrape the raw HTML of a web page.
+     */
+    scrape(url: string, options?: Omit<ProxyRequestOptions, "action">): Promise<string>;
+    /**
+     * Helper method to capture a screenshot of a web page (returns base64 data URI).
+     */
+    captureScreenshot(url: string, options?: Omit<ProxyRequestOptions, "action">): Promise<string>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAC,CAAS;gBAEZ,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAQnH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAUjD;;OAEG;IACG,OAAO,CACX,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,mBAAmB,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GACxD,OAAO,CAAC,aAAa,CAAC;IA6DzB;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK7F;;OAEG;IACG,iBAAiB,CACrB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAM,GAChD,OAAO,CAAC,MAAM,CAAC;CAInB"}

package/dist/index.js

@@ -0,0 +1,98 @@
+import { deriveKey, encryptPayload, decryptPayload } from "./crypto-helper.js";
+export class WebAgentProxyClient {
+    bridgeUrl;
+    defaultClientId;
+    encryptionKey;
+    apiKey;
+    constructor(options = {}) {
+        // Default to localhost bridge
+        this.bridgeUrl = (options.bridgeUrl || "http://localhost:8080").replace(/\/$/, "");
+        this.defaultClientId = options.defaultClientId;
+        this.encryptionKey = options.encryptionKey;
+        this.apiKey = options.apiKey;
+    }
+    getAuthHeaders() {
+        const headers = { "Content-Type": "application/json" };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        return headers;
+    }
+    /**
+     * Retrieves a list of all active browser clients connected to the bridge.
+     */
+    async getBrowsers() {
+        const response = await fetch(`${this.bridgeUrl}/api/browsers`, {
+            headers: this.getAuthHeaders(),
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch active browsers: ${response.statusText}`);
+        }
+        return response.json();
+    }
+    /**
+     * Routes a web request through a registered browser client.
+     */
+    async request(url, options = {}) {
+        const clientId = options.clientId || this.defaultClientId || "auto";
+        let requestBody = {
+            clientId,
+            url,
+        };
+        const action = options.action || "scrape";
+        const method = options.method || "GET";
+        const headers = options.headers || {};
+        const cookies = options.cookies || [];
+        if (this.encryptionKey) {
+            const key = deriveKey(this.encryptionKey);
+            const plaintextPayload = JSON.stringify({ url, action, method, headers, cookies });
+            const encrypted = encryptPayload(plaintextPayload, key);
+            requestBody.url = "[Encrypted]";
+            requestBody.encrypted = true;
+            requestBody.iv = encrypted.iv;
+            requestBody.tag = encrypted.tag;
+            requestBody.data = encrypted.data;
+        }
+        else {
+            requestBody.url = url;
+            requestBody.action = action;
+            requestBody.method = method;
+            requestBody.headers = headers;
+            requestBody.cookies = cookies;
+        }
+        const response = await fetch(`${this.bridgeUrl}/api/request`, {
+            method: "POST",
+            headers: this.getAuthHeaders(),
+            body: JSON.stringify(requestBody),
+        });
+        if (!response.ok) {
+            const errorData = (await response.json().catch(() => ({})));
+            throw new Error(errorData.error || `Proxy Request Failed: ${response.statusText}`);
+        }
+        const responseData = (await response.json());
+        if (responseData.encrypted) {
+            if (!this.encryptionKey) {
+                throw new Error("Received encrypted response, but no encryptionKey is configured.");
+            }
+            const key = deriveKey(this.encryptionKey);
+            const decryptedJson = decryptPayload(responseData.data, key, responseData.iv, responseData.tag);
+            return JSON.parse(decryptedJson);
+        }
+        return responseData;
+    }
+    /**
+     * Helper method to scrape the raw HTML of a web page.
+     */
+    async scrape(url, options = {}) {
+        const res = await this.request(url, { ...options, action: "scrape" });
+        return res.content || "";
+    }
+    /**
+     * Helper method to capture a screenshot of a web page (returns base64 data URI).
+     */
+    async captureScreenshot(url, options = {}) {
+        const res = await this.request(url, { ...options, action: "screenshot" });
+        return res.screenshot || "";
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@web-agent-proxy/sdk-js",
+  "version": "1.0.0",
+  "description": "JavaScript/TypeScript SDK client for Web Agent Proxy",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}

package/src/crypto-helper.ts

@@ -0,0 +1,45 @@
+import crypto from "crypto";
+
+export function deriveKey(passphrase: string): Buffer {
+  return crypto.createHash("sha256").update(passphrase).digest();
+}
+
+export interface EncryptedPayload {
+  iv: string;
+  tag: string;
+  data: string;
+}
+
+export function encryptPayload(plaintext: string, key: Buffer): EncryptedPayload {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  
+  let encrypted = cipher.update(plaintext, "utf8", "base64");
+  encrypted += cipher.final("base64");
+  
+  const tag = cipher.getAuthTag().toString("base64");
+  
+  return {
+    iv: iv.toString("base64"),
+    tag: tag,
+    data: encrypted,
+  };
+}
+
+export function decryptPayload(
+  ciphertext: string,
+  key: Buffer,
+  ivBase64: string,
+  tagBase64: string
+): string {
+  const iv = Buffer.from(ivBase64, "base64");
+  const tag = Buffer.from(tagBase64, "base64");
+  
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(tag);
+  
+  let decrypted = decipher.update(ciphertext, "base64", "utf8");
+  decrypted += decipher.final("utf8");
+  
+  return decrypted;
+}

package/src/index.ts

@@ -0,0 +1,147 @@
+import { deriveKey, encryptPayload, decryptPayload } from "./crypto-helper.js";
+
+export interface ProxyRequestOptions {
+  action?: "scrape" | "screenshot";
+  method?: string;
+  headers?: Record<string, string>;
+  cookies?: any[];
+}
+
+export interface ProxyResponse {
+  status: number;
+  headers: Record<string, string>;
+  content?: string;
+  screenshot?: string;
+  cookies?: any[];
+}
+
+export interface BrowserClientInfo {
+  id: string;
+  metadata: {
+    name: string;
+    platform: string;
+  };
+  status: "idle" | "busy";
+}
+
+export class WebAgentProxyClient {
+  private bridgeUrl: string;
+  private defaultClientId?: string;
+  private encryptionKey?: string;
+  private apiKey?: string;
+
+  constructor(options: { bridgeUrl?: string; defaultClientId?: string; encryptionKey?: string; apiKey?: string } = {}) {
+    // Default to localhost bridge
+    this.bridgeUrl = (options.bridgeUrl || "http://localhost:8080").replace(/\/$/, "");
+    this.defaultClientId = options.defaultClientId;
+    this.encryptionKey = options.encryptionKey;
+    this.apiKey = options.apiKey;
+  }
+
+  private getAuthHeaders(): Record<string, string> {
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    return headers;
+  }
+
+  /**
+   * Retrieves a list of all active browser clients connected to the bridge.
+   */
+  async getBrowsers(): Promise<BrowserClientInfo[]> {
+    const response = await fetch(`${this.bridgeUrl}/api/browsers`, {
+      headers: this.getAuthHeaders(),
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to fetch active browsers: ${response.statusText}`);
+    }
+    return response.json() as Promise<BrowserClientInfo[]>;
+  }
+
+  /**
+   * Routes a web request through a registered browser client.
+   */
+  async request(
+    url: string,
+    options: ProxyRequestOptions & { clientId?: string } = {}
+  ): Promise<ProxyResponse> {
+    const clientId = options.clientId || this.defaultClientId || "auto";
+
+    let requestBody: any = {
+      clientId,
+      url,
+    };
+
+    const action = options.action || "scrape";
+    const method = options.method || "GET";
+    const headers = options.headers || {};
+    const cookies = options.cookies || [];
+
+    if (this.encryptionKey) {
+      const key = deriveKey(this.encryptionKey);
+      const plaintextPayload = JSON.stringify({ url, action, method, headers, cookies });
+      const encrypted = encryptPayload(plaintextPayload, key);
+      
+      requestBody.url = "[Encrypted]";
+      requestBody.encrypted = true;
+      requestBody.iv = encrypted.iv;
+      requestBody.tag = encrypted.tag;
+      requestBody.data = encrypted.data;
+    } else {
+      requestBody.url = url;
+      requestBody.action = action;
+      requestBody.method = method;
+      requestBody.headers = headers;
+      requestBody.cookies = cookies;
+    }
+
+    const response = await fetch(`${this.bridgeUrl}/api/request`, {
+      method: "POST",
+      headers: this.getAuthHeaders(),
+      body: JSON.stringify(requestBody),
+    });
+
+    if (!response.ok) {
+      const errorData = (await response.json().catch(() => ({}))) as any;
+      throw new Error(errorData.error || `Proxy Request Failed: ${response.statusText}`);
+    }
+
+    const responseData = (await response.json()) as any;
+
+    if (responseData.encrypted) {
+      if (!this.encryptionKey) {
+        throw new Error("Received encrypted response, but no encryptionKey is configured.");
+      }
+      const key = deriveKey(this.encryptionKey);
+      const decryptedJson = decryptPayload(
+        responseData.data,
+        key,
+        responseData.iv,
+        responseData.tag
+      );
+      return JSON.parse(decryptedJson) as ProxyResponse;
+    }
+
+    return responseData as ProxyResponse;
+  }
+
+  /**
+   * Helper method to scrape the raw HTML of a web page.
+   */
+  async scrape(url: string, options: Omit<ProxyRequestOptions, "action"> = {}): Promise<string> {
+    const res = await this.request(url, { ...options, action: "scrape" });
+    return res.content || "";
+  }
+
+  /**
+   * Helper method to capture a screenshot of a web page (returns base64 data URI).
+   */
+  async captureScreenshot(
+    url: string,
+    options: Omit<ProxyRequestOptions, "action"> = {}
+  ): Promise<string> {
+    const res = await this.request(url, { ...options, action: "screenshot" });
+    return res.screenshot || "";
+  }
+}

package/test/client.test.mjs

@@ -0,0 +1,153 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { decryptPayload, deriveKey, encryptPayload } from "../dist/crypto-helper.js";
+import { WebAgentProxyClient } from "../dist/index.js";
+
+const originalFetch = globalThis.fetch;
+
+test.after(() => {
+  globalThis.fetch = originalFetch;
+});
+
+test("getBrowsers sends API key auth and parses browser metadata", async () => {
+  globalThis.fetch = async (input, init = {}) => {
+    assert.equal(input, "http://bridge.test/api/browsers");
+    assert.equal(init.headers.Authorization, "Bearer test-key");
+
+    return {
+      ok: true,
+      statusText: "OK",
+      json: async () => [
+        {
+          id: "br-a",
+          metadata: { name: "Local", platform: "desktop" },
+          status: "idle",
+        },
+      ],
+    };
+  };
+
+  const client = new WebAgentProxyClient({
+    bridgeUrl: "http://bridge.test/",
+    apiKey: "test-key",
+  });
+
+  const browsers = await client.getBrowsers();
+  assert.equal(browsers[0].id, "br-a");
+});
+
+test("request sends the plain SDK contract", async () => {
+  const cookies = [{ name: "session", value: "abc123", domain: ".example.com" }];
+
+  globalThis.fetch = async (input, init = {}) => {
+    assert.equal(input, "http://bridge.test/api/request");
+    assert.equal(init.method, "POST");
+    assert.equal(init.headers.Authorization, "Bearer test-key");
+
+    const body = JSON.parse(init.body);
+    assert.deepEqual(body, {
+      clientId: "br-default",
+      url: "https://example.com",
+      action: "scrape",
+      method: "GET",
+      headers: { "Accept-Language": "en-US" },
+      cookies,
+    });
+
+    return {
+      ok: true,
+      statusText: "OK",
+      json: async () => ({
+        status: 200,
+        headers: { "content-type": "text/html" },
+        content: "<html>ok</html>",
+        cookies: [],
+      }),
+    };
+  };
+
+  const client = new WebAgentProxyClient({
+    bridgeUrl: "http://bridge.test/",
+    defaultClientId: "br-default",
+    apiKey: "test-key",
+  });
+
+  const result = await client.request("https://example.com", {
+    headers: { "Accept-Language": "en-US" },
+    cookies,
+  });
+
+  assert.equal(result.status, 200);
+  assert.equal(result.content, "<html>ok</html>");
+});
+
+test("request encrypts payloads and decrypts encrypted responses", async () => {
+  const clearUrl = "https://example.com/private";
+  const key = deriveKey("shared-secret");
+
+  globalThis.fetch = async (_input, init = {}) => {
+    const bodyText = init.body;
+    const body = JSON.parse(bodyText);
+
+    assert.equal(body.clientId, "auto");
+    assert.equal(body.url, "[Encrypted]");
+    assert.equal(body.encrypted, true);
+    assert.equal(bodyText.includes(clearUrl), false);
+
+    const decryptedRequest = JSON.parse(decryptPayload(body.data, key, body.iv, body.tag));
+    assert.deepEqual(decryptedRequest, {
+      url: clearUrl,
+      action: "screenshot",
+      method: "POST",
+      headers: { "X-Test": "yes" },
+      cookies: [],
+    });
+
+    const encryptedResponse = encryptPayload(
+      JSON.stringify({
+        status: 201,
+        headers: {},
+        screenshot: "data:image/png;base64,abc",
+      }),
+      key
+    );
+
+    return {
+      ok: true,
+      statusText: "OK",
+      json: async () => ({
+        encrypted: true,
+        ...encryptedResponse,
+      }),
+    };
+  };
+
+  const client = new WebAgentProxyClient({
+    bridgeUrl: "http://bridge.test",
+    encryptionKey: "shared-secret",
+  });
+
+  const result = await client.request(clearUrl, {
+    action: "screenshot",
+    method: "POST",
+    headers: { "X-Test": "yes" },
+  });
+
+  assert.equal(result.status, 201);
+  assert.equal(result.screenshot, "data:image/png;base64,abc");
+});
+
+test("request surfaces bridge error payloads", async () => {
+  globalThis.fetch = async () => ({
+    ok: false,
+    statusText: "Gateway Timeout",
+    json: async () => ({ error: "Gateway Timeout (Queue Timeout 60s)" }),
+  });
+
+  const client = new WebAgentProxyClient({ bridgeUrl: "http://bridge.test" });
+
+  await assert.rejects(
+    () => client.request("https://example.com"),
+    /Queue Timeout 60s/
+  );
+});

package/test/crypto-helper.test.mjs

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { decryptPayload, deriveKey, encryptPayload } from "../dist/crypto-helper.js";
+
+test("deriveKey returns a deterministic AES-256 key", () => {
+  const keyA = deriveKey("shared-secret");
+  const keyB = deriveKey("shared-secret");
+
+  assert.equal(keyA.length, 32);
+  assert.deepEqual(keyA, keyB);
+});
+
+test("encryptPayload and decryptPayload round-trip JSON payloads", () => {
+  const key = deriveKey("shared-secret");
+  const plaintext = JSON.stringify({
+    url: "https://example.com/report",
+    headers: { "Accept-Language": "en-US" },
+    cookies: [{ name: "session", value: "abc123" }],
+  });
+
+  const encrypted = encryptPayload(plaintext, key);
+
+  assert.notEqual(encrypted.data, plaintext);
+  assert.equal(decryptPayload(encrypted.data, key, encrypted.iv, encrypted.tag), plaintext);
+});
+
+test("decryptPayload rejects tampered ciphertext", () => {
+  const key = deriveKey("shared-secret");
+  const encrypted = encryptPayload("sensitive payload", key);
+  const tamperedData = `${encrypted.data.slice(0, -2)}AA`;
+
+  assert.throws(() => {
+    decryptPayload(tamperedData, key, encrypted.iv, encrypted.tag);
+  }, Error);
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}