@scrapechain/oxylabs NPM

@scrapechain/oxylabs

A lightweight, unofficial SDK for using Oxylabs proxies. Includes helper methods for rotating sessions, generating endpoints, and more — all provided through a consistent interface shared across proxy providers.

🚀 Features

Converts proxy options into a ready-to-use URL
Built-in defaults for protocol, endpoint, port, and session behavior
Easy session rotation to change IP addresses
Normalized configuration interface across all ScrapeChain proxy SDKs

📦 Installation

  npm install @scrapechain/oxylabs

⚡ Quickstart

`Init proxy`

import { OxylabsResidentialProxy } from '@scrapechain/oxylabs';

const proxy = new OxylabsResidentialProxy({
  username: 'yourOxylabsUsername',
  password: 'yourPassword',
  country: 'United States of America',
  sticky: true,
});

Construct your proxy with Proxy Properties.

`.toUrl()`

const proxyUrl = proxy.toUrl();

console.log(proxyUrl);

http://customer-yourOxylabsUsername-cc-US-sessid-3469265147-sesstime-10:yourPassword@pr.oxylabs.io:7777

Returns a full proxy URL string.

Since the sticky property is truthy, it embeds a random sessionid in the username.

The session length defaults to 10 min, but can be changed with stickySessionDurationMinutes (max 30 min). The sessionid will stay the same until .rotate() is invoked or manually overridden with the property stickySessionId.

`.rotate()`

proxy.rotate();

Sets sessionid to a random number, which will point to a new IP address.

`.pingIP()`

const ipDetails = await proxy.pingIp();

console.log(ipDetails)

{
  success: true,
  ip: "76.91.176.189",
  latencyMs: 714,
}

Verifies the proxy is working and returns the IP and latency.

This will make a quick request to https://api.ipify.org/?format=json

`.details`

console.log(proxy.details)

{
  protocol: "http",
  endpoint: "pr.oxylabs.io",
  port: 7777,
  username: "customer-yourOxylabsUsername-cc-US-sessid-5245948176-sesstime-10",
  password: "yourPassword",
}

Returns a structured object with proxy connection details.

This is part of a common interface shared across all providers.

⚙️ Proxy properties

Property	Type	Required	Default	Description
`username`	`string`	✅	—	Your Oxylabs customer username.
`password`	`string`	✅	—	Your Oxylabs password.
`country`	`Country` (string enum)	❌	—	Country to geo-target the proxy IP.
`sticky`	`boolean`	❌	`false`	Enables sticky sessions (same IP across requests).
`stickySessionId`	`number`	❌	Auto-generated	Custom session ID for sticky mode (optional override).
`stickySessionDurationMinutes`	`number`	❌	`10`	Duration of sticky session in minutes.
`port`	`number`	❌	`7777`	Proxy port.
`endpoint`	`string`	❌	`pr.oxylabs.io`	Proxy hostname.
`protocol`	`"http"`, `"https"`, `"socks5"`	❌	`"http"`	Proxy protocol to use.