NstBrowserDotNetSDK 2.0.3

NSTBrowser .NET SDK - Unofficial Implementation

[License: MIT](https://opensource.org/licenses/MIT)

A comprehensive, unofficial .NET client library for the NSTBrowser API. This package allows developers to seamlessly integrate with NSTBrowser's browser technology in their .NET applications.

DISCLAIMER: This is an unofficial, independently developed implementation. This project is not affiliated with, endorsed by, or officially connected to NSTBrowser or its parent company.

Features

• Profile Management: Create, update, delete, and manage browser profiles with unique fingerprints
• Browser Control: Launch, manage, and interact with browser instances
• Environment Variable Support: Configure API endpoint and credentials via environment variables
• CDP Integration: Access to Chrome DevTools Protocol for advanced browser automation
• Proxy Configuration: Integrate with HTTP, SOCKS, and other proxy types
• Fingerprint Customization: Configure detailed browser fingerprints
• Tag & Group Organization: Organize profiles with tags and groups
• Async/Await Support: Modern C# async patterns for all operations

Installation

Install the package via NuGet Package Manager:

Install-Package NstBrowserDotNetSDK

Or via .NET CLI:

dotnet add package NstBrowserDotNetSDK

Quick Start

using NstBrowserDotNetSDK;
using NstBrowserDotNetSDK.Models;
using System;
using System.Threading.Tasks;
using Serilog;

class Program
{
    static async Task Main(string[] args)
    {
        // Initialize the client with your API key
        // You can also use environment variables by setting:
        // - NSTBROWSER_API_URL
        // - NSTBROWSER_API_KEY
        var client = new NstBrowserApiClient("http://localhost:8848/api/v2", "YOUR_API_KEY", Log.Logger);
        
        // Create a new browser profile
        var profileRequest = new CreateProfileRequest
        {
            Name = "My Test Profile",
            Platform = "win",
            KernelMilestone = "114",
            Proxy = "http://user:pass@proxy.example.com:8080",
            Fingerprint = new LaunchFingerprint
            {
                UserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36",
                HardwareConcurrency = 4,
                DeviceMemory = 8
            }
        };
        
        var profile = await client.CreateProfileAsync(profileRequest);
        Console.WriteLine($"Created profile with ID: {profile.Data?.ProfileId}");
        
        // Launch a browser instance using the profile
        var browser = await client.StartBrowserAsync(profile.Data?.ProfileId);
        Console.WriteLine($"Browser launched with debugging address: {browser.Data?.WebSocketDebuggerUrl}");
        
        // Get all open browser instances
        var browsers = await client.GetBrowsersAsync();
        
        // Stop the browser
        await client.StopBrowserAsync(profile.Data?.ProfileId);
    }
}

Configuration

Client Initialization

You can initialize the client in several ways:

// Method 1: Explicit parameters
var client = new NstBrowserApiClient(
    baseUrl: "http://localhost:8848/api/v2", 
    apiKey: "YOUR_API_KEY",
    logger: Log.Logger
);

// Method 2: Using environment variables
// Set these environment variables before running your application:
// - NSTBROWSER_API_URL=http://localhost:8848/api/v2
// - NSTBROWSER_API_KEY=YOUR_API_KEY
var client = new NstBrowserApiClient();

// Method 3: Mixed approach (fall back to environment variables if parameters are null)
var client = new NstBrowserApiClient(baseUrl: null, apiKey: null);

API Documentation

Browser Operations

// Start a browser by profile ID
var browser = await client.StartBrowserAsync("profile-id-here");

// Get all running browser instances
var browsers = await client.GetBrowsersAsync();

// Start a one-time browser session with custom configuration
var onceBrowser = await client.StartOnceBrowserAsync(new StartOnceBrowserRequest {
    Platform = "win",
    KernelMilestone = "114",
    Headless = "false",
    Incognito = true
});

// Start multiple browsers by profile IDs
await client.StartBrowsersAsync(
    new List<string> { "profile-id-1", "profile-id-2" },
    headless: "true" // Optional headless mode
);

// Stop a browser by profile ID
await client.StopBrowserAsync("profile-id-here");

// Get open DevTools pages for a browser profile
var pages = await client.GetBrowserPagesAsync("profile-id-here");

WebSocket/CDP Connections

// Connect to an existing browser (WebSocket/CDP) by profile ID
var wsConnection = await client.ConnectBrowserAsync("profile-id-here");

// Connect to a one-time browser by configuration
var wsOnceBrowser = await client.ConnectOnceBrowserAsync("{\"platform\":\"win\",\"kernelMilestone\":\"114\"}");

Profile Management

// Get a paged list of profiles with filtering options
var request = new ProfilesRequestArgs()
    .WithPage(1)
    .WithPageSize(50)
    .WithSearchQuery("test profile")
    .WithTags("important", "automation")
    .WithGroupId("group-id-here");

var profiles = await client.GetProfilesAsync(request);

// Create a new profile
var newProfile = await client.CreateProfileAsync(new CreateProfileRequest {
    Name = "My Profile",
    Platform = "win",
    KernelMilestone = "114",
    StartupUrls = new List<string> { "https://example.com" }
});

// Delete a single profile
await client.DeleteProfileAsync("profile-id-here");

// Delete multiple profiles
await client.DeleteProfilesAsync(new List<string> { "profile-id-1", "profile-id-2" });

// Enumerate all profiles with automatic pagination (.NET Standard 2.1+)
await foreach (var profile in client.GetAllProfilesAsync(new ProfilesRequestArgs())) {
    Console.WriteLine($"Profile: {profile.Name}, ID: {profile.ProfileId}");
}

// For .NET Standard 2.0:
foreach (var profile in client.GetAllProfiles(new ProfilesRequestArgs())) {
    Console.WriteLine($"Profile: {profile.Name}, ID: {profile.ProfileId}");
}

Profile Groups

// Get all profile groups
var groups = await client.GetAllProfileGroupsAsync();

// Get profile groups filtered by name
var filteredGroups = await client.GetAllProfileGroupsAsync("Group Name");

// Change the group for a profile
await client.ChangeProfileGroupAsync("profile-id-here", "new-group-id");

// Batch change the group for multiple profiles
await client.BatchChangeProfileGroupAsync(
    "new-group-id",
    new List<string> { "profile-id-1", "profile-id-2" }
);

Proxy Configuration

// Update proxy for a profile
await client.UpdateProfileProxyAsync("profile-id-here", new UpdateProfileProxyRequest {
    Protocol = "http",
    Host = "proxy.example.com",
    Port = "8080",
    Username = "user",
    Password = "pass"
});

// Alternative using URL format
await client.UpdateProfileProxyAsync("profile-id-here", new UpdateProfileProxyRequest {
    Url = "http://user:pass@proxy.example.com:8080"
});

// Batch update proxy for multiple profiles
await client.BatchUpdateProfileProxyAsync(
    new List<string> { "profile-id-1", "profile-id-2" },
    new UpdateProfileProxyRequest {
        Url = "http://user:pass@proxy.example.com:8080"
    }
);

// Reset proxy for a profile
await client.ResetProfileProxyAsync("profile-id-here");

// Batch reset proxy for multiple profiles
await client.BatchResetProfileProxyAsync(
    new List<string> { "profile-id-1", "profile-id-2" }
);

Profile Tags

// Add tags to a profile
await client.CreateProfileTagsAsync(
    "profile-id-here",
    new List<ProfileTag> { 
        new ProfileTag { Name = "tag1", Color = "#FF5733" }, 
        new ProfileTag { Name = "tag2", Color = "#33FF57" } 
    }
);

// Batch add tags to multiple profiles
await client.BatchCreateProfileTagsAsync(
    new List<string> { "profile-id-1", "profile-id-2" },
    new List<ProfileTag> { new ProfileTag { Name = "tag1", Color = "#3357FF" } }
);

// Update tags for a profile (replaces all existing tags)
await client.UpdateProfileTagsAsync(
    "profile-id-here",
    new List<ProfileTag> { new ProfileTag { Name = "new-tag", Color = "#5733FF" } }
);

// Clear tags from a profile
await client.ClearProfileTagsAsync("profile-id-here");

// Batch clear tags from multiple profiles
await client.BatchClearProfileTagsAsync(
    new List<string> { "profile-id-1", "profile-id-2" }
);

// Get all available tags in the system
var allTags = await client.GetProfileTagsAsync();

Local Data Management

// Clear profile cache
await client.ClearProfileCacheAsync("profile-id-here");

// Clear profile cookies
await client.ClearProfileCookiesAsync("profile-id-here");

Error Handling

The API client throws NSTApiException when errors occur. You can catch and handle these exceptions to implement custom error handling:

try {
    await client.StartBrowserAsync("profile-id-here");
} catch (NSTApiException ex) {
    Console.WriteLine($"API Error: {ex.Message}, Code: {ex.ErrorCode}");
    
    // Handle specific error codes
    if (ex.ErrorCode == 404) {
        Console.WriteLine("Profile not found");
    }
    
    // Access the original envelope if available
    if (ex.Envelope != null) {
        Console.WriteLine($"Additional info: {ex.Envelope.Msg}");
    }
}

Requirements

• .NET Standard 2.0 or higher
• Newtonsoft.Json
• Serilog for logging

License

This package is distributed under the MIT License. See the LICENSE file for details.

Disclaimer

This is an unofficial implementation and is not affiliated with, endorsed by, or officially connected to NSTBrowser. All trademarks, logos, and brand names are the property of their respective owners.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.