@linkvice/sdk

Official JavaScript/Node.js SDK for the LinkVice redirect management API.

Works in Node.js 14+ and modern browsers. Zero external dependencies.

Installation

npm install @linkvice/sdk

Or with Yarn:

yarn add @linkvice/sdk

Quick Start

const LinkVice = require('@linkvice/sdk');

const client = new LinkVice('your-api-key');

// List all domains
const domains = await client.getDomains();
console.log(domains.data);

Authentication

All API requests require a valid API key, passed as a Bearer token in the Authorization header. Obtain your key from the LinkVice dashboard.

const client = new LinkVice('your-api-key');

Configuration

The constructor accepts an optional second argument for configuration:

const client = new LinkVice('your-api-key', {
    baseUrl: 'https://www.linkvice.com/api/v1/',  // default
    timeout: 30000,                                 // milliseconds, default 30s
});

Option	Type	Default	Description
baseUrl	string	https://www.linkvice.com/api/v1/	API base URL
timeout	number	30000	Request timeout in ms

API Reference

Domains

getDomains()

List all domains on your account.

const response = await client.getDomains();
// response.data = [{ id: 1, domain: 'example.com', use_ssl: true, ... }, ...]

addDomain(domain, useSsl?)

Add a new domain.

Parameter	Type	Default	Description
domain	string	—	Domain name (e.g. "example.com")
useSsl	boolean	true	Enable SSL for the domain

const domain = await client.addDomain('example.com');
const domainNoSsl = await client.addDomain('example.com', false);

getDomain(id)

Get details for a specific domain.

const domain = await client.getDomain(42);

deleteDomain(id)

Delete a domain by ID.

await client.deleteDomain(42);

---

Redirects

getRedirects(options?)

List redirects with optional filtering and pagination.

Option	Type	Description
domainId	number	Filter by domain ID
page	number	Page number
perPage	number	Items per page

// All redirects
const all = await client.getRedirects();

// Filtered and paginated
const page = await client.getRedirects({ domainId: 5, page: 2, perPage: 25 });

createRedirect(data)

Create a new redirect.

Field	Type	Required	Description
domain_id	number	Yes	Domain to attach redirect to
target_url	string	Yes	Destination URL
redirect_type	string	No	"permanent" or "temporary"
http_code	number	No	301, 302, 307, or 308
language_rules	array	No	Language-based routing rules
image_redirect_url	string	No	Image redirect URL
block_bots	boolean	No	Block bot traffic
favicon_redirect	boolean	No	Enable favicon redirect
robots_redirect	boolean	No	Enable robots.txt redirect
ads_redirect	boolean	No	Enable ads.txt redirect
llm_redirect	boolean	No	Enable LLM redirect

// Simple redirect
const redirect = await client.createRedirect({
    domain_id: 5,
    target_url: 'https://destination.com/page',
    redirect_type: 'permanent',
    http_code: 301,
});

// With language rules
const multiLang = await client.createRedirect({
    domain_id: 5,
    target_url: 'https://en.example.com',
    http_code: 302,
    language_rules: [
        { language: 'de', target_url: 'https://de.example.com' },
        { language: 'fr', target_url: 'https://fr.example.com' },
    ],
    block_bots: true,
    favicon_redirect: true,
});

getRedirect(id)

Get details for a specific redirect.

const redirect = await client.getRedirect(123);

updateRedirect(id, data)

Update an existing redirect. Pass only the fields you want to change.

const updated = await client.updateRedirect(123, {
    target_url: 'https://new-destination.com',
    http_code: 302,
});

deleteRedirect(id)

Delete a redirect by ID.

await client.deleteRedirect(123);

---

Statistics

getRedirectStats(redirectId, filters?)

Get statistics for a specific redirect.

Filter	Type	Description
dateFrom	string	Start date (YYYY-MM-DD)
dateTo	string	End date (YYYY-MM-DD)
country	string	Country code (e.g. "US")
language	string	Language code (e.g. "en")

// All-time stats
const stats = await client.getRedirectStats(123);

// Filtered
const filtered = await client.getRedirectStats(123, {
    dateFrom: '2025-01-01',
    dateTo: '2025-12-31',
    country: 'US',
});

getDomainStats(domainId, filters?)

Get aggregated statistics for a domain. Accepts the same filters as getRedirectStats.

const stats = await client.getDomainStats(5, {
    dateFrom: '2025-06-01',
    dateTo: '2025-06-30',
});

---

Blacklist

getBlacklistRules(type?)

List blacklist rules, optionally filtered by type.

// All rules
const rules = await client.getBlacklistRules();

// Only IP rules
const ipRules = await client.getBlacklistRules('ip');

// Only user-agent rules
const uaRules = await client.getBlacklistRules('user_agent');

// Only referrer rules
const refRules = await client.getBlacklistRules('referrer');

addBlacklistRule(ruleType, pattern, options?)

Add a new blacklist rule.

Parameter	Type	Required	Description
ruleType	string	Yes	"ip", "referrer", or "user_agent"
pattern	string	Yes	Exact match string or regex pattern
isRegex	boolean	No	Whether pattern is a regex
note	string	No	Description of the rule

// Block a specific IP
await client.addBlacklistRule('ip', '192.168.1.100');

// Block referrers with regex
await client.addBlacklistRule('referrer', '.*spam\\.com$', {
    isRegex: true,
    note: 'Block all spam.com referrers',
});

// Block a user agent
await client.addBlacklistRule('user_agent', 'BadBot/1.0', {
    note: 'Known bad crawler',
});

deleteBlacklistRule(id)

Delete a blacklist rule by ID.

await client.deleteBlacklistRule(7);

---

Error Handling

All methods throw a LinkViceError on failure. The error includes the HTTP status code and the full response body when available.

const { LinkViceError } = require('@linkvice/sdk');

try {
    await client.getDomain(99999);
} catch (err) {
    if (err instanceof LinkViceError) {
        console.error('Status:', err.status);       // e.g. 404
        console.error('Message:', err.message);      // e.g. "Domain not found."
        console.error('Body:', err.responseBody);    // full API response
    }
}

---

Browser Usage

The SDK works in modern browsers that support the fetch API. Include it via a bundler (Webpack, Vite, esbuild, etc.):

import LinkVice from '@linkvice/sdk';

const client = new LinkVice('your-api-key');
const domains = await client.getDomains();

Or load directly in a script tag (after bundling or copying src/index.js):

<script src="path/to/linkvice-sdk.js"></script>
<script>
    const client = new LinkVice('your-api-key');
    client.getDomains().then(response => {
        console.log(response.data);
    });
</script>

---

Node.js Compatibility

Node.js Version	Support
18+	Full support (native fetch)
14 - 17	Supported via built-in https fallback
< 14	Not supported

The SDK uses native fetch when available (Node.js 18+). On older Node.js versions, it automatically falls back to the built-in https module.

---

Examples

Complete examples are available in the examples/ directory:

• examples/basic.js - CommonJS example with all API methods
• examples/basic.mjs - ES module example

Run them with:

export LINKVICE_API_KEY="your-api-key"
node examples/basic.js
node examples/basic.mjs

---

License

MIT - Copyright (c) 2024-2026 LinkVice.com