@dominusnode/sdk 1.0.0

package/dist/cjs/http.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const constants_js_1 = require("./constants.js");
+const errors_js_1 = require("./errors.js");
+// Sanitize parsed JSON to prevent prototype pollution from untrusted API responses
+// Recursive prototype pollution stripping (covers nested objects too)
+const DANGEROUS_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+// Depth limit prevents stack overflow on deeply nested JSON
+function stripDangerousKeys(obj, depth = 0) {
+    if (depth > 50 || !obj || typeof obj !== "object")
+        return;
+    if (Array.isArray(obj)) {
+        for (const item of obj)
+            stripDangerousKeys(item, depth + 1);
+        return;
+    }
+    const record = obj;
+    for (const key of Object.keys(record)) {
+        if (DANGEROUS_KEYS.has(key)) {
+            delete record[key];
+        }
+        else if (record[key] && typeof record[key] === "object") {
+            stripDangerousKeys(record[key], depth + 1);
+        }
+    }
+}
+function safeJsonParse(text) {
+    const parsed = JSON.parse(text);
+    stripDangerousKeys(parsed);
+    return parsed;
+}
+// Add jitter to retry delays to prevent thundering-herd on rate-limited endpoints
+function addJitter(ms) {
+    const jitter = ms * 0.2 * (Math.random() - 0.5); // ±10% jitter
+    return Math.max(100, Math.round(ms + jitter));
+}
+function throwForStatus(status, body, headers) {
+    let message;
+    try {
+        const parsed = JSON.parse(body);
+        message = parsed.error ?? parsed.message ?? body;
+    }
+    catch {
+        message = body;
+    }
+    // Truncate error message to prevent unbounded body in exception strings
+    if (message.length > 500)
+        message = message.slice(0, 500) + "... [truncated]";
+    switch (status) {
+        case 400: throw new errors_js_1.ValidationError(message);
+        case 401: throw new errors_js_1.AuthenticationError(message);
+        case 402: throw new errors_js_1.InsufficientBalanceError(message);
+        case 403: throw new errors_js_1.AuthorizationError(message);
+        case 404: throw new errors_js_1.NotFoundError(message);
+        case 409: throw new errors_js_1.ConflictError(message);
+        case 429: {
+            const parsed = parseInt(headers.get("retry-after") ?? "60", 10);
+            const retryAfter = Number.isFinite(parsed) ? parsed : 60; // NaN guard
+            throw new errors_js_1.RateLimitError(message, retryAfter);
+        }
+        default:
+            if (status >= 500)
+                throw new errors_js_1.ServerError(message);
+            throw new errors_js_1.DominusNodeError(message, status);
+    }
+}
+// Max response body size to prevent OOM from malicious/large API responses
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024; // 10 MB
+class HttpClient {
+    baseUrl;
+    tokenManager;
+    constructor(baseUrl, tokenManager) {
+        this.baseUrl = baseUrl;
+        this.tokenManager = tokenManager;
+    }
+    async request(opts) {
+        const headers = {
+            "User-Agent": constants_js_1.USER_AGENT,
+            "Content-Type": "application/json",
+            ...opts.headers,
+        };
+        if (opts.requiresAuth !== false) {
+            const token = await this.tokenManager.getValidToken();
+            // Guard against null/empty token to prevent "Bearer " header
+            if (!token) {
+                throw new Error("No valid token available. Call connectWithKey() or login() first.");
+            }
+            headers["Authorization"] = `Bearer ${token}`;
+        }
+        const url = `${this.baseUrl}${opts.path}`;
+        let response;
+        const timeoutMs = 30_000; // 30s request timeout
+        try {
+            response = await fetch(url, {
+                method: opts.method,
+                headers,
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                signal: AbortSignal.timeout(timeoutMs),
+                redirect: "error", // Reject redirects — prevents HTTPS→HTTP credential leakage
+            });
+        }
+        catch (err) {
+            throw new errors_js_1.NetworkError(err instanceof Error ? err.message : "Network request failed");
+        }
+        if (response.status === 429) {
+            // Auto-retry once on rate limit (cap wait at 10s to avoid client-side DoS)
+            const parsed = parseInt(response.headers.get("retry-after") ?? "5", 10);
+            const retryAfter = Number.isFinite(parsed) ? parsed : 5; // NaN guard
+            // Cancel body stream instead of buffering — prevents OOM from large 429 responses
+            await response.body?.cancel();
+            await new Promise((resolve) => setTimeout(resolve, addJitter(Math.min(retryAfter * 1000, 10_000))));
+            // Refresh token before retry in case it expired during the wait
+            if (opts.requiresAuth !== false) {
+                const freshToken = await this.tokenManager.getValidToken();
+                headers["Authorization"] = `Bearer ${freshToken}`;
+            }
+            try {
+                response = await fetch(url, {
+                    method: opts.method,
+                    headers,
+                    body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                    signal: AbortSignal.timeout(timeoutMs),
+                    redirect: "error",
+                });
+            }
+            catch (err) {
+                throw new errors_js_1.NetworkError(err instanceof Error ? err.message : "Network request failed");
+            }
+        }
+        if (response.status === 401 && opts.requiresAuth !== false) {
+            // Cancel body stream before retry to prevent memory leak from unconsumed response
+            await response.body?.cancel();
+            // Force a token refresh (don't reuse the rejected token) and retry once
+            try {
+                const newToken = await this.tokenManager.forceRefresh();
+                headers["Authorization"] = `Bearer ${newToken}`;
+                const retry = await fetch(url, {
+                    method: opts.method,
+                    headers,
+                    body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                    signal: AbortSignal.timeout(timeoutMs),
+                    redirect: "error",
+                });
+                // Apply response size limit to 401 retry path too
+                const retryContentLength = parseInt(retry.headers.get("content-length") ?? "0", 10);
+                if (retryContentLength > MAX_RESPONSE_BYTES) {
+                    throw new errors_js_1.ServerError("Response body too large");
+                }
+                const retryText = await retry.text();
+                if (retryText.length > MAX_RESPONSE_BYTES) {
+                    throw new errors_js_1.ServerError("Response body exceeds size limit");
+                }
+                if (retry.ok) {
+                    return retryText ? safeJsonParse(retryText) : {};
+                }
+                throwForStatus(retry.status, retryText, retry.headers);
+            }
+            catch (err) {
+                if (err instanceof errors_js_1.DominusNodeError)
+                    throw err;
+                // Refresh failed — fall through to original 401 handling
+            }
+        }
+        // Enforce response body size limit to prevent OOM
+        const contentLength = parseInt(response.headers.get("content-length") ?? "0", 10);
+        if (contentLength > MAX_RESPONSE_BYTES) {
+            throw new errors_js_1.ServerError("Response body too large");
+        }
+        const responseText = await response.text();
+        if (responseText.length > MAX_RESPONSE_BYTES) {
+            throw new errors_js_1.ServerError("Response body exceeds size limit");
+        }
+        if (!response.ok) {
+            throwForStatus(response.status, responseText, response.headers);
+        }
+        return responseText ? safeJsonParse(responseText) : {};
+    }
+    async get(path, requiresAuth = true) {
+        return this.request({ method: "GET", path, requiresAuth });
+    }
+    async post(path, body, requiresAuth = true) {
+        return this.request({ method: "POST", path, body, requiresAuth });
+    }
+    async put(path, body) {
+        return this.request({ method: "PUT", path, body });
+    }
+    async patch(path, body) {
+        return this.request({ method: "PATCH", path, body });
+    }
+    async delete(path) {
+        return this.request({ method: "DELETE", path });
+    }
+}
+exports.HttpClient = HttpClient;

package/dist/cjs/index.d.ts

@@ -0,0 +1,30 @@
+export { DominusNodeClient } from "./client.js";
+export { AuthResource } from "./auth.js";
+export { KeysResource } from "./keys.js";
+export type { CreateKeyResponse, ListKeysResponse } from "./keys.js";
+export { WalletResource } from "./wallet.js";
+export type { WalletBalanceResponse, TransactionsResponse, StripeCheckoutResponse, CryptoInvoiceResponse, ForecastResponse, } from "./wallet.js";
+export { UsageResource } from "./usage.js";
+export type { DateRangeOptions as UsageDateRangeOptions, UsageSummary, UsageResponse, DailyUsageDay, DailyUsageResponse, TopHostEntry, TopHostsResponse, } from "./usage.js";
+export { PlansResource } from "./plans.js";
+export type { PlanEntry, ListPlansResponse, UserPlanResponse, ChangePlanResponse, } from "./plans.js";
+export { SessionsResource } from "./sessions.js";
+export type { ActiveSessionEntry, ActiveSessionsResponse } from "./sessions.js";
+export { ProxyResource } from "./proxy.js";
+export type { ProxyHealthResponse, ProxyStatusResponse } from "./proxy.js";
+export { AdminResource } from "./admin.js";
+export { SlotsResource } from "./slots.js";
+export { AgenticWalletResource } from "./resources/agent-wallet.js";
+export type { AgenticWallet, AgenticWalletTransaction, AgenticWalletListResponse, AgenticWalletFundResponse, AgenticWalletTransactionsResponse, AgenticWalletDeleteResponse, } from "./resources/agent-wallet.js";
+export { TeamsResource } from "./resources/teams.js";
+export type { Team, TeamMember, TeamInvite, TeamListResponse, TeamMembersResponse, TeamInvitesResponse, TeamKeysResponse, TeamKeyCreateResponse, TeamDeleteResponse, TeamFundResponse, TeamTransactionsResponse, } from "./resources/teams.js";
+export { X402Resource } from "./resources/x402.js";
+export type { X402Info, X402Facilitator, X402Pricing, } from "./resources/x402.js";
+export { WalletAuthResource } from "./resources/wallet-auth.js";
+export type { WalletChallenge, WalletVerifyResult, WalletLinkResult, } from "./resources/wallet-auth.js";
+export type { DateRangeOptions as AdminDateRangeOptions, ListUsersResponse, GetUserResponse, RevenueResponse, DailyRevenueEntry, DailyRevenueResponse, } from "./admin.js";
+export { HttpClient } from "./http.js";
+export type { HttpOptions } from "./http.js";
+export { DominusNodeError, AuthenticationError, AuthorizationError, RateLimitError, InsufficientBalanceError, ValidationError, NotFoundError, ConflictError, ServerError, NetworkError, ProxyError, } from "./errors.js";
+export type { DominusNodeConfig, User, ApiKey, Wallet, WalletTransaction, UsageRecord, TopHost, Plan, ActiveSession, ProxyUrlOptions, ProxyHealth, ProxyConfig, StripeCheckout, CryptoInvoice, AdminUser, RevenueStats, DailyRevenue, SystemStats, MfaStatus, MfaSetup, LoginResult, TokenPair, SlotsInfo, WaitlistJoinResult, WaitlistCount, } from "./types.js";
+export { SDK_VERSION, USER_AGENT, DEFAULT_BASE_URL, DEFAULT_PROXY_HOST, DEFAULT_HTTP_PROXY_PORT, DEFAULT_SOCKS5_PROXY_PORT, } from "./constants.js";

package/dist/cjs/index.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SOCKS5_PROXY_PORT = exports.DEFAULT_HTTP_PROXY_PORT = exports.DEFAULT_PROXY_HOST = exports.DEFAULT_BASE_URL = exports.USER_AGENT = exports.SDK_VERSION = exports.ProxyError = exports.NetworkError = exports.ServerError = exports.ConflictError = exports.NotFoundError = exports.ValidationError = exports.InsufficientBalanceError = exports.RateLimitError = exports.AuthorizationError = exports.AuthenticationError = exports.DominusNodeError = exports.HttpClient = exports.WalletAuthResource = exports.X402Resource = exports.TeamsResource = exports.AgenticWalletResource = exports.SlotsResource = exports.AdminResource = exports.ProxyResource = exports.SessionsResource = exports.PlansResource = exports.UsageResource = exports.WalletResource = exports.KeysResource = exports.AuthResource = exports.DominusNodeClient = void 0;
+// Main client
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "DominusNodeClient", { enumerable: true, get: function () { return client_js_1.DominusNodeClient; } });
+// Resource modules
+var auth_js_1 = require("./auth.js");
+Object.defineProperty(exports, "AuthResource", { enumerable: true, get: function () { return auth_js_1.AuthResource; } });
+var keys_js_1 = require("./keys.js");
+Object.defineProperty(exports, "KeysResource", { enumerable: true, get: function () { return keys_js_1.KeysResource; } });
+var wallet_js_1 = require("./wallet.js");
+Object.defineProperty(exports, "WalletResource", { enumerable: true, get: function () { return wallet_js_1.WalletResource; } });
+var usage_js_1 = require("./usage.js");
+Object.defineProperty(exports, "UsageResource", { enumerable: true, get: function () { return usage_js_1.UsageResource; } });
+var plans_js_1 = require("./plans.js");
+Object.defineProperty(exports, "PlansResource", { enumerable: true, get: function () { return plans_js_1.PlansResource; } });
+var sessions_js_1 = require("./sessions.js");
+Object.defineProperty(exports, "SessionsResource", { enumerable: true, get: function () { return sessions_js_1.SessionsResource; } });
+var proxy_js_1 = require("./proxy.js");
+Object.defineProperty(exports, "ProxyResource", { enumerable: true, get: function () { return proxy_js_1.ProxyResource; } });
+var admin_js_1 = require("./admin.js");
+Object.defineProperty(exports, "AdminResource", { enumerable: true, get: function () { return admin_js_1.AdminResource; } });
+var slots_js_1 = require("./slots.js");
+Object.defineProperty(exports, "SlotsResource", { enumerable: true, get: function () { return slots_js_1.SlotsResource; } });
+var agent_wallet_js_1 = require("./resources/agent-wallet.js");
+Object.defineProperty(exports, "AgenticWalletResource", { enumerable: true, get: function () { return agent_wallet_js_1.AgenticWalletResource; } });
+var teams_js_1 = require("./resources/teams.js");
+Object.defineProperty(exports, "TeamsResource", { enumerable: true, get: function () { return teams_js_1.TeamsResource; } });
+var x402_js_1 = require("./resources/x402.js");
+Object.defineProperty(exports, "X402Resource", { enumerable: true, get: function () { return x402_js_1.X402Resource; } });
+var wallet_auth_js_1 = require("./resources/wallet-auth.js");
+Object.defineProperty(exports, "WalletAuthResource", { enumerable: true, get: function () { return wallet_auth_js_1.WalletAuthResource; } });
+// Infrastructure (HttpClient for advanced custom integrations)
+var http_js_1 = require("./http.js");
+Object.defineProperty(exports, "HttpClient", { enumerable: true, get: function () { return http_js_1.HttpClient; } });
+// TokenManager is internal — not exported to prevent misuse of token lifecycle
+// Errors
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "DominusNodeError", { enumerable: true, get: function () { return errors_js_1.DominusNodeError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
+Object.defineProperty(exports, "AuthorizationError", { enumerable: true, get: function () { return errors_js_1.AuthorizationError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_js_1.RateLimitError; } });
+Object.defineProperty(exports, "InsufficientBalanceError", { enumerable: true, get: function () { return errors_js_1.InsufficientBalanceError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_js_1.ValidationError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_js_1.NotFoundError; } });
+Object.defineProperty(exports, "ConflictError", { enumerable: true, get: function () { return errors_js_1.ConflictError; } });
+Object.defineProperty(exports, "ServerError", { enumerable: true, get: function () { return errors_js_1.ServerError; } });
+Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return errors_js_1.NetworkError; } });
+Object.defineProperty(exports, "ProxyError", { enumerable: true, get: function () { return errors_js_1.ProxyError; } });
+// Constants
+var constants_js_1 = require("./constants.js");
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return constants_js_1.SDK_VERSION; } });
+Object.defineProperty(exports, "USER_AGENT", { enumerable: true, get: function () { return constants_js_1.USER_AGENT; } });
+Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return constants_js_1.DEFAULT_BASE_URL; } });
+Object.defineProperty(exports, "DEFAULT_PROXY_HOST", { enumerable: true, get: function () { return constants_js_1.DEFAULT_PROXY_HOST; } });
+Object.defineProperty(exports, "DEFAULT_HTTP_PROXY_PORT", { enumerable: true, get: function () { return constants_js_1.DEFAULT_HTTP_PROXY_PORT; } });
+Object.defineProperty(exports, "DEFAULT_SOCKS5_PROXY_PORT", { enumerable: true, get: function () { return constants_js_1.DEFAULT_SOCKS5_PROXY_PORT; } });

package/dist/cjs/keys.d.ts

@@ -0,0 +1,27 @@
+import type { HttpClient } from "./http.js";
+export interface CreateKeyResponse {
+    key: string;
+    id: string;
+    prefix: string;
+    label: string;
+    created_at: string;
+}
+export interface ListKeysResponse {
+    keys: Array<{
+        id: string;
+        prefix: string;
+        label: string;
+        created_at: string;
+        revoked_at: string | null;
+    }>;
+}
+export declare class KeysResource {
+    private http;
+    constructor(http: HttpClient);
+    /** Create a new API key. The raw key is returned only once. */
+    create(label?: string): Promise<CreateKeyResponse>;
+    /** List all API keys for the authenticated user. */
+    list(): Promise<ListKeysResponse>;
+    /** Revoke an API key by its ID. */
+    revoke(id: string): Promise<void>;
+}

package/dist/cjs/keys.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeysResource = void 0;
+class KeysResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Create a new API key. The raw key is returned only once. */
+    async create(label) {
+        return this.http.post("/api/keys", { label: label ?? "Default" });
+    }
+    /** List all API keys for the authenticated user. */
+    async list() {
+        return this.http.get("/api/keys");
+    }
+    /** Revoke an API key by its ID. */
+    async revoke(id) {
+        await this.http.delete(`/api/keys/${encodeURIComponent(id)}`);
+    }
+}
+exports.KeysResource = KeysResource;

package/dist/cjs/plans.d.ts

@@ -0,0 +1,37 @@
+import type { HttpClient } from "./http.js";
+export interface PlanEntry {
+    id: string;
+    name: string;
+    pricePerGbCents: number;
+    pricePerGbUsd: number;
+    monthlyBandwidthBytes: number;
+    monthlyBandwidthGB: number | null;
+    isDefault: boolean;
+}
+export interface ListPlansResponse {
+    plans: PlanEntry[];
+}
+export interface UserPlanResponse {
+    plan: PlanEntry;
+    usage: {
+        monthlyUsageBytes: number;
+        monthlyUsageGB: number;
+        limitBytes: number;
+        limitGB: number | null;
+        percentUsed: number | null;
+    };
+}
+export interface ChangePlanResponse {
+    message: string;
+    plan: PlanEntry;
+}
+export declare class PlansResource {
+    private http;
+    constructor(http: HttpClient);
+    /** List all available plans (does not require authentication). */
+    list(): Promise<ListPlansResponse>;
+    /** Get the current user's plan and monthly usage. */
+    getUserPlan(): Promise<UserPlanResponse>;
+    /** Change the current user's plan. */
+    changePlan(planId: string): Promise<ChangePlanResponse>;
+}

package/dist/cjs/plans.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlansResource = void 0;
+class PlansResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** List all available plans (does not require authentication). */
+    async list() {
+        return this.http.get("/api/plans", false);
+    }
+    /** Get the current user's plan and monthly usage. */
+    async getUserPlan() {
+        return this.http.get("/api/plans/user/plan");
+    }
+    /** Change the current user's plan. */
+    async changePlan(planId) {
+        return this.http.put("/api/plans/user/plan", { planId });
+    }
+}
+exports.PlansResource = PlansResource;

package/dist/cjs/proxy.d.ts

@@ -0,0 +1,62 @@
+import type { HttpClient } from "./http.js";
+import type { ProxyUrlOptions, ProxyConfig, DominusNodeConfig } from "./types.js";
+export interface ProxyHealthResponse {
+    status: string;
+    activeSessions: number;
+    uptimeSeconds: number;
+}
+export interface ProxyStatusResponse {
+    status: string;
+    activeSessions: number;
+    userActiveSessions: number;
+    avgLatencyMs: number;
+    providers: Array<{
+        name: string;
+        state: string;
+        consecutiveFailures: number;
+        totalRequests: number;
+        totalErrors: number;
+        avgLatencyMs: number;
+        fallbackOnly: boolean;
+    }>;
+    endpoints: {
+        http: string;
+        socks5: string;
+    };
+    supportedCountries: string[];
+    uptimeSeconds: number;
+}
+export declare class ProxyResource {
+    private http;
+    private proxyHost;
+    private httpPort;
+    private socks5Port;
+    constructor(http: HttpClient, config: DominusNodeConfig);
+    /**
+     * Build a proxy URL string for use with HTTP clients.
+     *
+     * The returned URL includes authentication via the username field.
+     * Geo-targeting and sticky sessions are encoded in the username portion
+     * following Dominus Node proxy conventions.
+     *
+     * @param apiKey - The API key to authenticate proxy requests.
+     * @param opts   - Optional targeting parameters (protocol, country, etc.).
+     * @returns A fully-formed proxy URL string.
+     *
+     * @example
+     * ```ts
+     * const url = client.proxy.buildUrl("dn_live_abc123");
+     * // => "http://user:dn_live_abc123@proxy.dominusnode.com:8080"
+     *
+     * const socksUrl = client.proxy.buildUrl("dn_live_abc123", { protocol: "socks5", country: "US" });
+     * // => "socks5://user-country-US:dn_live_abc123@proxy.dominusnode.com:1080"
+     * ```
+     */
+    buildUrl(apiKey: string, opts?: ProxyUrlOptions): string;
+    /** Get public proxy health status (does not require authentication). */
+    getHealth(): Promise<ProxyHealthResponse>;
+    /** Get detailed proxy status including provider info (requires authentication). */
+    getStatus(): Promise<ProxyStatusResponse>;
+    /** Get proxy server configuration (requires authentication). */
+    getConfig(): Promise<ProxyConfig>;
+}

package/dist/cjs/proxy.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyResource = void 0;
+const constants_js_1 = require("./constants.js");
+class ProxyResource {
+    http;
+    proxyHost;
+    httpPort;
+    socks5Port;
+    constructor(http, config) {
+        this.http = http;
+        this.proxyHost = config.proxyHost ?? constants_js_1.DEFAULT_PROXY_HOST;
+        // Validate proxyHost to prevent URL injection via crafted hostnames
+        if (/[\s\/\\@?#]/.test(this.proxyHost)) {
+            throw new Error("proxyHost contains invalid characters");
+        }
+        this.httpPort = config.httpProxyPort ?? constants_js_1.DEFAULT_HTTP_PROXY_PORT;
+        this.socks5Port = config.socks5ProxyPort ?? constants_js_1.DEFAULT_SOCKS5_PROXY_PORT;
+    }
+    /**
+     * Build a proxy URL string for use with HTTP clients.
+     *
+     * The returned URL includes authentication via the username field.
+     * Geo-targeting and sticky sessions are encoded in the username portion
+     * following Dominus Node proxy conventions.
+     *
+     * @param apiKey - The API key to authenticate proxy requests.
+     * @param opts   - Optional targeting parameters (protocol, country, etc.).
+     * @returns A fully-formed proxy URL string.
+     *
+     * @example
+     * ```ts
+     * const url = client.proxy.buildUrl("dn_live_abc123");
+     * // => "http://user:dn_live_abc123@proxy.dominusnode.com:8080"
+     *
+     * const socksUrl = client.proxy.buildUrl("dn_live_abc123", { protocol: "socks5", country: "US" });
+     * // => "socks5://user-country-US:dn_live_abc123@proxy.dominusnode.com:1080"
+     * ```
+     */
+    buildUrl(apiKey, opts) {
+        const protocol = opts?.protocol ?? "http";
+        const port = protocol === "socks5" ? this.socks5Port : this.httpPort;
+        // Build username with geo-targeting parameters (URL-encoded to prevent injection)
+        const userParts = ["user"];
+        if (opts?.country)
+            userParts.push(`country-${encodeURIComponent(opts.country)}`);
+        if (opts?.state)
+            userParts.push(`state-${encodeURIComponent(opts.state)}`);
+        if (opts?.city)
+            userParts.push(`city-${encodeURIComponent(opts.city)}`);
+        if (opts?.asn)
+            userParts.push(`asn-${encodeURIComponent(String(opts.asn))}`);
+        if (opts?.sessionId)
+            userParts.push(`session-${encodeURIComponent(opts.sessionId)}`);
+        const username = userParts.join("-");
+        return `${protocol}://${username}:${encodeURIComponent(apiKey)}@${this.proxyHost}:${port}`;
+    }
+    /** Get public proxy health status (does not require authentication). */
+    async getHealth() {
+        return this.http.get("/api/proxy/health", false);
+    }
+    /** Get detailed proxy status including provider info (requires authentication). */
+    async getStatus() {
+        return this.http.get("/api/proxy/status");
+    }
+    /** Get proxy server configuration (requires authentication). */
+    async getConfig() {
+        return this.http.get("/api/proxy/config");
+    }
+}
+exports.ProxyResource = ProxyResource;

package/dist/cjs/resources/agent-wallet.d.ts

@@ -0,0 +1,52 @@
+import type { HttpClient } from "../http.js";
+export interface AgenticWallet {
+    id: string;
+    label: string;
+    balanceCents: number;
+    spendingLimitCents: number;
+    dailyLimitCents: number | null;
+    allowedDomains: string[] | null;
+    status: string;
+    createdAt: string;
+}
+export interface AgenticWalletTransaction {
+    id: string;
+    walletId: string;
+    type: string;
+    amountCents: number;
+    description: string;
+    sessionId: string | null;
+    createdAt: string;
+}
+export interface AgenticWalletListResponse {
+    wallets: AgenticWallet[];
+}
+export interface AgenticWalletFundResponse {
+    transaction: AgenticWalletTransaction;
+}
+export interface AgenticWalletTransactionsResponse {
+    transactions: AgenticWalletTransaction[];
+}
+export interface AgenticWalletDeleteResponse {
+    deleted: boolean;
+    refundedCents: number;
+}
+export declare class AgenticWalletResource {
+    private http;
+    constructor(http: HttpClient);
+    create(label: string, spendingLimitCents?: number, options?: {
+        dailyLimitCents?: number | null;
+        allowedDomains?: string[] | null;
+    }): Promise<AgenticWallet>;
+    list(): Promise<AgenticWalletListResponse>;
+    get(walletId: string): Promise<AgenticWallet>;
+    fund(walletId: string, amountCents: number): Promise<AgenticWalletFundResponse>;
+    updateWalletPolicy(walletId: string, policy: {
+        dailyLimitCents?: number | null;
+        allowedDomains?: string[] | null;
+    }): Promise<AgenticWallet>;
+    transactions(walletId: string, limit?: number, offset?: number): Promise<AgenticWalletTransactionsResponse>;
+    freeze(walletId: string): Promise<AgenticWallet>;
+    unfreeze(walletId: string): Promise<AgenticWallet>;
+    delete(walletId: string): Promise<AgenticWalletDeleteResponse>;
+}

package/dist/cjs/resources/agent-wallet.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgenticWalletResource = void 0;
+class AgenticWalletResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async create(label, spendingLimitCents = 10000, options) {
+        if (!Number.isInteger(spendingLimitCents) || spendingLimitCents < 0 || spendingLimitCents > 2_147_483_647) {
+            throw new Error("spendingLimitCents must be a non-negative integer <= 2,147,483,647");
+        }
+        if (options?.dailyLimitCents !== undefined && options.dailyLimitCents !== null) {
+            if (!Number.isInteger(options.dailyLimitCents) || options.dailyLimitCents < 0 || options.dailyLimitCents > 2_147_483_647) {
+                throw new Error("dailyLimitCents must be a non-negative integer <= 2,147,483,647");
+            }
+        }
+        const body = { label, spendingLimitCents };
+        if (options?.dailyLimitCents !== undefined)
+            body.dailyLimitCents = options.dailyLimitCents;
+        if (options?.allowedDomains !== undefined)
+            body.allowedDomains = options.allowedDomains;
+        return this.http.post("/api/agent-wallet", body);
+    }
+    async list() {
+        return this.http.get("/api/agent-wallet");
+    }
+    async get(walletId) {
+        return this.http.get(`/api/agent-wallet/${encodeURIComponent(walletId)}`);
+    }
+    async fund(walletId, amountCents) {
+        if (!Number.isInteger(amountCents) || amountCents <= 0 || amountCents > 2_147_483_647) {
+            throw new Error("amountCents must be a positive integer <= 2,147,483,647");
+        }
+        return this.http.post(`/api/agent-wallet/${encodeURIComponent(walletId)}/fund`, { amountCents });
+    }
+    async updateWalletPolicy(walletId, policy) {
+        if (policy.dailyLimitCents !== undefined && policy.dailyLimitCents !== null) {
+            if (!Number.isInteger(policy.dailyLimitCents) || policy.dailyLimitCents < 0 || policy.dailyLimitCents > 2_147_483_647) {
+                throw new Error("dailyLimitCents must be a non-negative integer <= 2,147,483,647");
+            }
+        }
+        return this.http.patch(`/api/agent-wallet/${encodeURIComponent(walletId)}/policy`, policy);
+    }
+    async transactions(walletId, limit, offset) {
+        const params = new URLSearchParams();
+        if (limit !== undefined)
+            params.set("limit", String(limit));
+        if (offset !== undefined)
+            params.set("offset", String(offset));
+        const qs = params.toString();
+        return this.http.get(`/api/agent-wallet/${encodeURIComponent(walletId)}/transactions${qs ? `?${qs}` : ""}`);
+    }
+    async freeze(walletId) {
+        return this.http.post(`/api/agent-wallet/${encodeURIComponent(walletId)}/freeze`, {});
+    }
+    async unfreeze(walletId) {
+        return this.http.post(`/api/agent-wallet/${encodeURIComponent(walletId)}/unfreeze`, {});
+    }
+    async delete(walletId) {
+        return this.http.delete(`/api/agent-wallet/${encodeURIComponent(walletId)}`);
+    }
+}
+exports.AgenticWalletResource = AgenticWalletResource;