Nstbrowser SDK for Node.js
A Node.js SDK for interacting with Nstbrowser API v2
Note: This documentation is for API v2, which is the recommended version with complete functionality from v1 plus additional features. For v1 documentation, please refer to README-v1.md. New users are encouraged to use v2 for a more stable and standardized experience.
Overview
This SDK implements Nstbrowser API v2, providing a comprehensive set of tools for managing browser profiles, controlling browser instances, managing local browser data, and utilizing Chrome DevTools Protocol (CDP) for browser automation.
The SDK enables you to:
- Create and manage browser profiles with detailed fingerprint configurations
- Start and stop browser instances individually or in batch
- Configure and manage proxies for profiles
- Manage profile tags for better organization
- Clear browser cache and cookies
- Connect to browsers using Chrome DevTools Protocol (CDP)
- Automate browser actions through CDP integration with Puppeteer
Installation
Using npm:
$ npm install nstbrowser-sdk-node
$ npm install nstbrowser-sdk-node
Using pnpm:
$ pnpm install nstbrowser-sdk-node
$ pnpm install nstbrowser-sdk-node
Using yarn:
$ yarn add nstbrowser-sdk-node
$ yarn add nstbrowser-sdk-node
Getting Started
To use the SDK, you need an API key from Nstbrowser:
import { NstBrowserV2 } from 'nstbrowser-sdk-node';
// Initialize the client with your API key
const client = new NstBrowserV2('your_api_key', {
timeout: 60000,
apiAddress: 'http://localhost:8848/api/v2'
});
// Now you can use the various services
const profileId = 'your_profile_id';
// Start a browser instance
const startResponse = await client.browsers().startBrowser({ profileId });
console.log('Browser started:', startResponse);
// Stop the browser instance
const stopResponse = await client.browsers().stopBrowser({ profileId });
console.log('Browser stopped:', stopResponse);
import { NstBrowserV2 } from 'nstbrowser-sdk-node';
// Initialize the client with your API key
const client = new NstBrowserV2('your_api_key', {
timeout: 60000,
apiAddress: 'http://localhost:8848/api/v2'
});
// Now you can use the various services
const profileId = 'your_profile_id';
// Start a browser instance
const startResponse = await client.browsers().startBrowser({ profileId });
console.log('Browser started:', startResponse);
// Stop the browser instance
const stopResponse = await client.browsers().stopBrowser({ profileId });
console.log('Browser stopped:', stopResponse);
CDP Integration with Puppeteer
One of the most powerful features of the SDK is its seamless integration with Puppeteer for browser automation:
import { NstBrowserV2 } from 'nstbrowser-sdk-node';
import puppeteer from 'puppeteer-core';
async function automateWithPuppeteer() {
const client = new NstBrowserV2('your_api_key');
// Connect to a browser using CDP
const cdpResponse = await client.cdpEndpoints().connectBrowser({
profileId: 'your_profile_id',
config: {
headless: false,
autoClose: false
}
});
// Connect Puppeteer to the browser instance
const browser = await puppeteer.connect({
browserWSEndpoint: cdpResponse.data.webSocketDebuggerUrl,
defaultViewport: null
});
// Use Puppeteer for automation
const page = await browser.newPage();
await page.goto('https://example.com');
// ... perform other actions
}
import { NstBrowserV2 } from 'nstbrowser-sdk-node';
import puppeteer from 'puppeteer-core';
async function automateWithPuppeteer() {
const client = new NstBrowserV2('your_api_key');
// Connect to a browser using CDP
const cdpResponse = await client.cdpEndpoints().connectBrowser({
profileId: 'your_profile_id',
config: {
headless: false,
autoClose: false
}
});
// Connect Puppeteer to the browser instance
const browser = await puppeteer.connect({
browserWSEndpoint: cdpResponse.data.webSocketDebuggerUrl,
defaultViewport: null
});
// Use Puppeteer for automation
const page = await browser.newPage();
await page.goto('https://example.com');
// ... perform other actions
}
Examples
The SDK comes with a comprehensive set of examples in the /examples/v2
directory. To run the examples:
- Navigate to the examples directory and install dependencies:
cd examples/v2
npm install
cd examples/v2
npm install
- Create a
.env
file in theexamples/v2
directory and add your API key:
echo "nstbrowser_api_key=your-api-key" > .env
echo "nstbrowser_api_key=your-api-key" > .env
- Run any example:
node browsers/startBrowser.js
node browsers/startBrowser.js
Available examples are organized by service:
Browser Examples
browsers/getBrowserDebugger.js
: Get browser debugger information for automationbrowsers/getBrowserPages.js
: Get information about browser pagesbrowsers/getBrowsers.js
: Get list of active browsers with status informationbrowsers/startBrowser.js
: Start a browser for a specific profilebrowsers/startBrowsers.js
: Start multiple browsers in batchbrowsers/startOnceBrowser.js
: Start a once-off browser with custom configurationbrowsers/stopBrowser.js
: Stop a specific browser instancebrowsers/stopBrowsers.js
: Stop multiple browser instances in batch
Profile Examples
profiles/batchClearProfileTags.js
: Clear tags for multiple profiles in batchprofiles/batchCreateProfileTags.js
: Create tags for multiple profiles in batchprofiles/batchResetProfileProxy.js
: Reset proxies for multiple profiles in batchprofiles/batchUpdateProfileTags.js
: Update tags for multiple profiles in batchprofiles/batchUpdateProxy.js
: Update proxies for multiple profiles in batchprofiles/clearProfileTags.js
: Clear all tags from a specific profileprofiles/createProfile.js
: Create a new profile with detailed configurationprofiles/createProfileTags.js
: Create new tags for a specific profileprofiles/deleteProfile.js
: Delete a specific profileprofiles/deleteProfiles.js
: Delete multiple profiles in batchprofiles/getProfileTags.js
: Get all tags associated with profilesprofiles/getProfiles.js
: Get profiles with filtering optionsprofiles/resetProfileProxy.js
: Reset proxy configuration for a specific profileprofiles/updateProfileProxy.js
: Update proxy configuration for a specific profileprofiles/updateProfileTags.js
: Update tags for a specific profileprofiles/getAllProfileGroups.js
: Get all profile groupsprofiles/changeProfileGroup.js
: Change a profile groupprofiles/batchChangeProfileGroup.js
: Batch changes to profile groups
Local Data Examples
locals/clearProfileCache.js
: Clear browser cache for a specific profilelocals/clearProfileCookies.js
: Clear browser cookies for a specific profile
CDP Endpoint Examples
cdpEndpoints/connectBrowser.js
: Connect to a browser using CDP and automate with PuppeteercdpEndpoints/connectOnceBrowser.js
: Connect to a once-off browser with CDP and automate with Puppeteer
Support
For support, feel free to reach out to us via Discord. For more detailed documentation, visit the official Nstbrowser documentation: Nstbrowser API Documentation.