webshare-rest-sdk

CLI and TypeScript SDK for the Webshare REST API, built around the documented endpoints at https://apidocs.webshare.io/.

This package is dependency-free at runtime and uses the platform fetch API. Node 18+ is supported.

Install

npm install webshare-rest-sdk

Install the CLI globally from npm after it is published:

npm install -g webshare-rest-sdk
webshare --help

Install directly from GitHub after pushing the repo:

npm install -g github:OWNER/REPO
webshare --help

For local use from this workspace:

npm install
npm run build

Run it locally without installing globally:

npm run cli -- --help
npm run cli -- proxies list --mode direct

Or link the command globally:

npm link
webshare --help

Package it as a tarball:

npm pack
npm install -g ./webshare-rest-sdk-0.1.0.tgz

Publish to npm:

npm login
npm publish

CLI

Open the interactive TUI to save your token and defaults:

webshare tui

The TUI writes config to ~/.config/webshare-cli/config.json with file mode 600.

You can also set your token non-interactively:

webshare config set-token "your_api_token"
webshare config set-defaults --mode direct --page-size 25 --plan-id 123
webshare config show

Then use the webshare command:

webshare profile get
webshare proxies list --mode direct --page-size 25
webshare proxies list --mode direct --all
webshare proxies refresh --plan-id 123
webshare proxy-config get --plan-id 123
webshare api-keys list

You can pass the token inline too:

webshare --token "your_api_token" proxies list --mode direct

Token priority is --token, then WEBSHARE_API_TOKEN, then the saved config.

Use the raw REST escape hatch for any endpoint:

webshare request GET proxy/list/ --query mode=direct --query page_size=25
webshare request PATCH profile/ --body '{"timezone":"UTC"}'
webshare request POST proxy/replace/ --body @replace.json

Download endpoints print text/binary directly:

webshare proxies download --download-token "proxy_list_download_token" --country-codes US,FR
webshare stats download-activity --query download_token=activity_download_token

Run webshare --help for the command list.

Quick Start

import { WebshareClient } from "webshare-rest-sdk";

const webshare = new WebshareClient({
  token: process.env.WEBSHARE_API_TOKEN,
});

const proxies = await webshare.proxies.list({
  mode: "direct",
  page: 1,
  pageSize: 25,
  countryCodeIn: ["US", "FR"],
});

for await (const proxy of webshare.proxies.iterate({ mode: "direct" })) {
  console.log(proxy.proxy_address, proxy.port);
}

Covered Resources

The SDK exposes wrappers for Webshare's documented REST resources:

• auth, twoFactor, profile, notifications
• proxies, proxyConfig, ipAuthorizations, proxyReplacement, proxyStats
• subscription, billing, referral
• verification, idVerification, subUsers
• downloads, apiKeys

You can also call raw endpoints:

await webshare.request("GET", "proxy/list/", {
  query: { mode: "direct", page_size: 25 },
});

Errors

Non-2xx responses throw WebshareApiError with status, headers, and parsed body.

import { WebshareApiError } from "webshare-rest-sdk";

try {
  await webshare.profile.get();
} catch (error) {
  if (error instanceof WebshareApiError) {
    console.error(error.status, error.body);
  }
}

Notes

Most Webshare endpoints use https://proxy.webshare.io/api/v2/, while a few documented proxy configuration and replacement endpoints use /api/v3/. The SDK handles both.