@xyz17711/proxy-pool 0.1.0 → 0.1.2

package/README.md

@@ -18,17 +18,20 @@ npm install @xyz17711/proxy-pool
 
 | Method | Description |
 | --- | --- |
-| `getBestProxy` | Returns one of the fastest verified-alive proxies matching the filter, randomized to spread load ($0.001, x402) |
+| `getBestProxy` | Free proxy API: get one fast, verified-alive proxy (HTTP, SOCKS) filtered by country, protocol and anonymity, for scraping ($0.010, x402) |
 
 ## Quickstart
 
 ```typescript
 import { Client } from "@xyz17711/proxy-pool";
 
-const client = new Client("https://api.17711.xyz/registry/proxy-pool");
+const client = new Client(); // talks to https://api.17711.xyz/registry/proxy-pool by default
 // see the Methods table above for every available call and its request/response type
 ```
 
+Pass another base URL (self-hosted instance, test server) as the first argument:
+`new Client("https://my-host.example/registry/proxy-pool")`.
+
 ## Paying past the free quota
 
 Every gated tool allows a small number of free calls per day; beyond that it returns a 402
@@ -38,7 +41,7 @@ network, and payee address attached:
 ```typescript
 import { Client, PaymentRequiredError } from "@xyz17711/proxy-pool";
 
-const client = new Client("https://api.17711.xyz/registry/proxy-pool");
+const client = new Client();
 try {
   await client.getBestProxy(/* ... */);
 } catch (e) {
@@ -54,7 +57,7 @@ own environment/secrets manager, never a literal string in source code:
 ```typescript
 import { Client } from "@xyz17711/proxy-pool";
 
-const client = new Client("https://api.17711.xyz/registry/proxy-pool", {
+const client = new Client({
   x402PrivateKey: process.env.X402_PRIVATE_KEY,
   x402ExpectedNetwork: "eip155:8453", // Base mainnet; use eip155:84532 for Base Sepolia testnet
   x402MaxPaymentUsdc: 0.01,           // refuse any single call above this
@@ -73,7 +76,7 @@ with that same key in this process.
 import { Client } from "@xyz17711/proxy-pool";
 import { ProxyPoolToolkit } from "@xyz17711/proxy-pool/langchain";
 
-const client = new Client("https://api.17711.xyz/registry/proxy-pool", { /* ...wallet options... */ });
+const client = new Client({ /* ...wallet options... */ });
 const tools = new ProxyPoolToolkit(client).getTools();
 ```
 

package/dist/index.d.ts

@@ -24,9 +24,18 @@ export interface ProxyView {
 export interface GetBestProxyResponse {
     proxy: ProxyView;
 }
+/** Production base URL of this service; pass another to self-host or test. */
+export declare const DEFAULT_BASE_URL = "https://api.17711.xyz/registry/proxy-pool";
 /** Typed client for proxy-pool, e.g. `client.getBestProxy(...)`. */
 export declare class Client extends BaseClient {
-    /** Returns one of the fastest verified-alive proxies matching the filter, randomized to spread load ($0.001, x402) */
+    /**
+     * `new Client()` talks to the production service. Pass a base URL to target another
+     * instance, and/or wallet options (`new Client({ x402PrivateKey, ... })`) to pay past the
+     * free quota automatically.
+     */
+    constructor(options?: ClientOptions);
+    constructor(baseUrl?: string, options?: ClientOptions);
+    /** Free proxy API: get one fast, verified-alive proxy (HTTP, SOCKS) filtered by country, protocol and anonymity, for scraping ($0.010, x402) */
     getBestProxy(params: {
         anonymity?: string | null;
         city?: string | null;

package/dist/index.js

@@ -2,9 +2,17 @@
  * Typed HTTP client and request/response interfaces for proxy-pool.
  */
 import { Client as BaseClient } from "@xyz17711/core";
+/** Production base URL of this service; pass another to self-host or test. */
+export const DEFAULT_BASE_URL = "https://api.17711.xyz/registry/proxy-pool";
 /** Typed client for proxy-pool, e.g. `client.getBestProxy(...)`. */
 export class Client extends BaseClient {
-    /** Returns one of the fastest verified-alive proxies matching the filter, randomized to spread load ($0.001, x402) */
+    constructor(baseUrlOrOptions, options = {}) {
+        const [url, opts] = typeof baseUrlOrOptions === "object"
+            ? [DEFAULT_BASE_URL, baseUrlOrOptions]
+            : [baseUrlOrOptions ?? DEFAULT_BASE_URL, options];
+        super(url, opts);
+    }
+    /** Free proxy API: get one fast, verified-alive proxy (HTTP, SOCKS) filtered by country, protocol and anonymity, for scraping ($0.010, x402) */
     async getBestProxy(params) {
         return this.get("/v1/proxy-pool/get_best_proxy", { anonymity: params.anonymity, city: params.city, country: params.country, protocol: params.protocol });
     }

package/dist/langchain.js

@@ -11,7 +11,7 @@ export class ProxyPoolToolkit {
         return [
             tool(async (input) => this.client.getBestProxy(input), {
                 name: "getBestProxy",
-                description: "Returns one of the fastest verified-alive proxies matching the filter, randomized to spread load ($0.001, x402)",
+                description: "Free proxy API: get one fast, verified-alive proxy (HTTP, SOCKS) filtered by country, protocol and anonymity, for scraping ($0.010, x402)",
                 schema: z.object({ anonymity: z.string().nullable().optional(), city: z.string().nullable().optional(), country: z.string().nullable().optional(), protocol: z.string().nullable().optional() }),
             }),
         ];

package/package.json

@@ -1,7 +1,35 @@
 {
   "name": "@xyz17711/proxy-pool",
-  "version": "0.1.0",
-  "description": "Generated typed client for the proxy-pool 17711.xyz microservice.",
+  "version": "0.1.2",
+  "description": "Typed TypeScript client for the 17711.xyz Proxy Pool API: pay-per-call, settled in USDC via x402.",
+  "license": "MIT",
+  "author": "17711 Services",
+  "homepage": "https://api.17711.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/17711-services/clients.git",
+    "directory": "node/packages/proxy-pool"
+  },
+  "bugs": {
+    "url": "https://github.com/17711-services/clients/issues"
+  },
+  "keywords": [
+    "x402",
+    "usdc",
+    "api-client",
+    "pay-per-call",
+    "ai-agents",
+    "mcp",
+    "langchain",
+    "proxy-pool"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -1,39 +0,0 @@
-/**
- * Typed HTTP client and request/response interfaces for proxy-pool.
- */
-
-import { Client as BaseClient, type ClientOptions } from "@xyz17711/core";
-
-/** A `SourceProxy` joined with its `CheckedProxy` result, if it has been checked at least once -- what every read tool actually filters/returns. */
-export interface ProxyView {
-  anonymity: string;
-  /** `None` if this service has never checked this proxy yet. */
-  checked_alive?: boolean | null;
-  checked_at?: number | null;
-  /** See `CheckedProxy::consecutive_successes`'s own doc comment. `0` if never checked. */
-  checked_consecutive_successes: number;
-  /** See `CheckedProxy::ema_latency_ms`'s own doc comment. */
-  checked_ema_latency_ms?: number | null;
-  checked_latency_ms?: number | null;
-  checked_protocol?: string | null;
-  city: string;
-  country: string;
-  id: string;
-  ip: string;
-  port: number;
-  protocols: string[];
-}
-
-export interface GetBestProxyResponse {
-  proxy: ProxyView;
-}
-
-/** Typed client for proxy-pool, e.g. `client.getBestProxy(...)`. */
-export class Client extends BaseClient {
-  /** Returns one of the fastest verified-alive proxies matching the filter, randomized to spread load ($0.001, x402) */
-  async getBestProxy(params: { anonymity?: string | null; city?: string | null; country?: string | null; protocol?: string | null }): Promise<GetBestProxyResponse> {
-    return this.get<GetBestProxyResponse>("/v1/proxy-pool/get_best_proxy", { anonymity: params.anonymity, city: params.city, country: params.country, protocol: params.protocol });
-  }
-}
-
-export { ClientOptions };

package/src/langchain.ts

@@ -1,28 +0,0 @@
-/**
- * LangChain.js tools for proxy-pool, grouped in one Toolkit -- one tool per operation, each just an async function (JS has no separate sync form to generate). Requires the `@langchain/core`+`zod` peer dependencies declared in this package's own package.json -- imported from `proxy-pool/langchain`, never from the package root, so importing the base client never requires them installed.
- */
-
-import { tool } from "@langchain/core/tools";
-import { z } from "zod";
-import { Client } from "./index.js";
-
-export class ProxyPoolToolkit {
-  private client: Client;
-
-  constructor(client: Client) {
-    this.client = client;
-  }
-
-  getTools() {
-    return [
-      tool(
-        async (input) => this.client.getBestProxy(input),
-        {
-          name: "getBestProxy",
-          description: "Returns one of the fastest verified-alive proxies matching the filter, randomized to spread load ($0.001, x402)",
-          schema: z.object({ anonymity: z.string().nullable().optional(), city: z.string().nullable().optional(), country: z.string().nullable().optional(), protocol: z.string().nullable().optional() }),
-        },
-      ),
-    ];
-  }
-}

package/test/index.test.mjs

@@ -1,24 +0,0 @@
-/**
- * Verifies every proxy-pool client method sends a request to the expected path/HTTP verb and parses a well-formed response -- one test per operation, real fetch mocked via a plain reassignment of `globalThis.fetch` (no extra test/mocking dependency). Runs against the COMPILED package (`../dist/index.js`) -- build before testing.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { Client } from "../dist/index.js";
-
-test("getBestProxy calls the expected path", async () => {
-  const originalFetch = globalThis.fetch;
-  globalThis.fetch = async (url, init = {}) => {
-    const parsed = new URL(url);
-    assert.equal((init.method ?? "GET").toUpperCase(), "GET");
-    assert.equal(parsed.pathname, "/v1/proxy-pool/get_best_proxy");
-    return new Response(JSON.stringify({ proxy: { anonymity: "test", checked_alive: null, checked_at: null, checked_consecutive_successes: 0, checked_ema_latency_ms: null, checked_latency_ms: null, checked_protocol: null, city: "test", country: "test", id: "test", ip: "test", port: 0, protocols: [] } }), { status: 200 });
-  };
-  try {
-    const client = new Client("https://example.test");
-    const result = await client.getBestProxy({ anonymity: null, city: null, country: null, protocol: null });
-    assert.ok(result !== undefined);
-  } finally {
-    globalThis.fetch = originalFetch;
-  }
-});

package/test/langchain.test.mjs

@@ -1,16 +0,0 @@
-/**
- * Verifies every proxy-pool LangChain tool through the real StructuredTool (`.invoke()`), not just the underlying client method -- catches schema-shape bugs a plain client-method test would miss. Requires the `langchain`/`zod` dev dependencies.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { Client } from "../dist/index.js";
-import { ProxyPoolToolkit } from "../dist/langchain.js";
-
-test("getBestProxy tool invoke", async () => {
-  globalThis.fetch = async () => new Response(JSON.stringify({ proxy: { anonymity: "test", checked_alive: null, checked_at: null, checked_consecutive_successes: 0, checked_ema_latency_ms: null, checked_latency_ms: null, checked_protocol: null, city: "test", country: "test", id: "test", ip: "test", port: 0, protocols: [] } }), { status: 200 });
-  const toolkit = new ProxyPoolToolkit(new Client("https://example.test"));
-  const t = toolkit.getTools().find((x) => x.name === "getBestProxy");
-  const result = await t.invoke({ anonymity: "test", city: "test", country: "test", protocol: "test" });
-  assert.ok(result !== undefined);
-});

package/tsconfig.json

@@ -1,16 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ES2020",
-    "moduleResolution": "bundler",
-    "declaration": true,
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true
-  },
-  "include": [
-    "src"
-  ]
-}