@dominusnode/mastra-tools 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominus Node
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @dominusnode/mastra-tools
+
+DomiNode rotating proxy tools for [Mastra AI](https://mastra.ai) agents.
+
+Provides 23 tools for interacting with DomiNode's rotating proxy-as-a-service platform from Mastra AI workflows and agents.
+
+## Installation
+
+```bash
+npm install @dominusnode/mastra-tools
+```
+
+## Quick Start
+
+```typescript
+import { DominusNodeToolkit } from "@dominusnode/mastra-tools";
+
+const toolkit = new DominusNodeToolkit({
+  apiKey: process.env.DOMINUSNODE_API_KEY!, // dn_live_... or dn_test_...
+});
+
+// Get all tools for your Mastra agent
+const tools = toolkit.getTools();
+
+// Use individually
+const balance = await toolkit.checkBalance();
+```
+
+## Configuration
+
+| Environment Variable | Description | Default |
+|---|---|---|
+| `DOMINUSNODE_API_KEY` | API key (required) | -- |
+| `DOMINUSNODE_BASE_URL` | REST API base URL | `https://api.dominusnode.com` |
+| `DOMINUSNODE_PROXY_HOST` | Proxy gateway host | `proxy.dominusnode.com` |
+| `DOMINUSNODE_PROXY_PORT` | Proxy gateway port | `8080` |
+
+## Available Tools (23)
+
+### Proxy Operations
+- `dominusnode_proxied_fetch` - Fetch a URL through the rotating proxy with geo-targeting
+- `dominusnode_check_balance` - Check wallet balance and remaining bandwidth
+- `dominusnode_check_usage` - View bandwidth usage statistics
+- `dominusnode_get_proxy_config` - Get proxy pools, pricing, and endpoints
+- `dominusnode_list_sessions` - List active proxy sessions
+
+### Agentic Wallet Management
+- `dominusnode_create_agentic_wallet` - Create a custodial sub-wallet
+- `dominusnode_fund_agentic_wallet` - Transfer funds to an agentic wallet
+- `dominusnode_agentic_wallet_balance` - Check agentic wallet balance
+- `dominusnode_list_agentic_wallets` - List all agentic wallets
+- `dominusnode_agentic_transactions` - Get agentic wallet transaction history
+- `dominusnode_freeze_agentic_wallet` - Freeze an agentic wallet
+- `dominusnode_unfreeze_agentic_wallet` - Unfreeze an agentic wallet
+- `dominusnode_delete_agentic_wallet` - Delete an agentic wallet
+
+### Team Management
+- `dominusnode_create_team` - Create a team with shared wallet
+- `dominusnode_list_teams` - List all teams
+- `dominusnode_team_details` - Get team details
+- `dominusnode_team_fund` - Fund a team wallet
+- `dominusnode_team_create_key` - Create a team API key
+- `dominusnode_team_usage` - Get team transaction history
+- `dominusnode_update_team` - Update team settings
+- `dominusnode_update_team_member_role` - Change a member's role
+
+### Payments
+- `dominusnode_topup_paypal` - Top up wallet via PayPal
+- `dominusnode_x402_info` - Get x402 micropayment protocol info
+
+## Security
+
+- Full SSRF protection (private IP blocking, DNS rebinding, Teredo/6to4, hex/octal/decimal normalization)
+- OFAC sanctioned country blocking (CU, IR, KP, RU, SY)
+- Credential scrubbing in all error messages
+- Prototype pollution prevention on all parsed JSON
+- HTTP method restriction (GET/HEAD/OPTIONS only for proxied fetch)
+- 10 MB response cap, 4000 char truncation, 30s timeout
+- Redirect following disabled
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @dominusnode/mastra-tools
+ *
+ * DomiNode rotating proxy tools for Mastra AI agents.
+ * Provides 23 tools for proxy fetching, wallet management,
+ * team collaboration, and payment operations.
+ *
+ * @example
+ * ```typescript
+ * import { DominusNodeToolkit } from "@dominusnode/mastra-tools";
+ *
+ * const toolkit = new DominusNodeToolkit({
+ *   apiKey: process.env.DOMINUSNODE_API_KEY!,
+ * });
+ *
+ * const tools = toolkit.getTools();
+ * ```
+ */
+export { DominusNodeToolkit, isPrivateIp, validateTargetUrl, validateCountry, validateUuid, normalizeIpv4, stripDangerousKeys, scrubCredentials, truncate, formatBytes, formatCents, } from "./toolkit.js";
+export type { DominusNodeToolkitConfig } from "./toolkit.js";

package/dist/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * @dominusnode/mastra-tools
+ *
+ * DomiNode rotating proxy tools for Mastra AI agents.
+ * Provides 23 tools for proxy fetching, wallet management,
+ * team collaboration, and payment operations.
+ *
+ * @example
+ * ```typescript
+ * import { DominusNodeToolkit } from "@dominusnode/mastra-tools";
+ *
+ * const toolkit = new DominusNodeToolkit({
+ *   apiKey: process.env.DOMINUSNODE_API_KEY!,
+ * });
+ *
+ * const tools = toolkit.getTools();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCents = exports.formatBytes = exports.truncate = exports.scrubCredentials = exports.stripDangerousKeys = exports.normalizeIpv4 = exports.validateUuid = exports.validateCountry = exports.validateTargetUrl = exports.isPrivateIp = exports.DominusNodeToolkit = void 0;
+var toolkit_js_1 = require("./toolkit.js");
+Object.defineProperty(exports, "DominusNodeToolkit", { enumerable: true, get: function () { return toolkit_js_1.DominusNodeToolkit; } });
+// Security utilities (exported for testing)
+Object.defineProperty(exports, "isPrivateIp", { enumerable: true, get: function () { return toolkit_js_1.isPrivateIp; } });
+Object.defineProperty(exports, "validateTargetUrl", { enumerable: true, get: function () { return toolkit_js_1.validateTargetUrl; } });
+Object.defineProperty(exports, "validateCountry", { enumerable: true, get: function () { return toolkit_js_1.validateCountry; } });
+Object.defineProperty(exports, "validateUuid", { enumerable: true, get: function () { return toolkit_js_1.validateUuid; } });
+Object.defineProperty(exports, "normalizeIpv4", { enumerable: true, get: function () { return toolkit_js_1.normalizeIpv4; } });
+Object.defineProperty(exports, "stripDangerousKeys", { enumerable: true, get: function () { return toolkit_js_1.stripDangerousKeys; } });
+Object.defineProperty(exports, "scrubCredentials", { enumerable: true, get: function () { return toolkit_js_1.scrubCredentials; } });
+Object.defineProperty(exports, "truncate", { enumerable: true, get: function () { return toolkit_js_1.truncate; } });
+Object.defineProperty(exports, "formatBytes", { enumerable: true, get: function () { return toolkit_js_1.formatBytes; } });
+Object.defineProperty(exports, "formatCents", { enumerable: true, get: function () { return toolkit_js_1.formatCents; } });

package/dist/toolkit.d.ts

@@ -0,0 +1,244 @@
+/**
+ * DomiNode Mastra AI Toolkit
+ *
+ * Implements 24 tools for interacting with DomiNode's rotating proxy service
+ * from Mastra AI agents and workflows.
+ *
+ * Uses createTool() from @mastra/core/tools with Zod schemas.
+ *
+ * Security:
+ *  - Full SSRF protection (private IP blocking, DNS rebinding, .localhost, embedded creds)
+ *  - Credential scrubbing in error messages
+ *  - Response truncation at 4000 chars for LLM context efficiency
+ *  - OFAC sanctioned country validation
+ *  - Prototype pollution prevention (recursive)
+ *  - HTTP method restriction (GET/HEAD/OPTIONS only for proxied fetch)
+ *  - 10 MB response cap, 30s timeout
+ *  - Redirect following disabled
+ */
+export interface DominusNodeToolkitConfig {
+    /** DomiNode API key (dn_live_... or dn_test_...). Falls back to DOMINUSNODE_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL of the DomiNode REST API. */
+    baseUrl?: string;
+    /** Hostname of the DomiNode proxy gateway. */
+    proxyHost?: string;
+    /** Port of the DomiNode proxy gateway. */
+    proxyPort?: number;
+}
+/** Remove any dn_live_* or dn_test_* tokens from error messages. */
+export declare function scrubCredentials(msg: string): string;
+export declare function truncate(text: string, max?: number): string;
+/**
+ * Normalize non-standard IPv4 representations to dotted-decimal.
+ * Handles: decimal integers (2130706433), hex (0x7f000001), octal octets (0177.0.0.1).
+ */
+export declare function normalizeIpv4(hostname: string): string | null;
+export declare function isPrivateIp(hostname: string): boolean;
+/**
+ * Validate a URL for safety before proxying.
+ * Blocks: private IPs, localhost, .local/.internal/.arpa, embedded credentials, non-http(s).
+ */
+export declare function validateTargetUrl(url: string): URL;
+/**
+ * Validate a country code: must be 2 uppercase letters and not OFAC sanctioned.
+ */
+export declare function validateCountry(country: string | undefined): string | undefined;
+/**
+ * Validate a UUID string.
+ */
+export declare function validateUuid(id: string, label: string): string;
+export declare function stripDangerousKeys(obj: unknown, depth?: number): void;
+export declare function formatBytes(bytes: number): string;
+export declare function formatCents(cents: number): string;
+export declare class DominusNodeToolkit {
+    private apiKey;
+    private baseUrl;
+    private proxyHost;
+    private proxyPort;
+    private cachedJwt;
+    private jwtExpiresAt;
+    constructor(config?: DominusNodeToolkitConfig);
+    private getApiKey;
+    private ensureAuth;
+    private apiRequest;
+    private apiGet;
+    private apiPost;
+    private apiDelete;
+    private apiPatch;
+    proxiedFetch(url: string, method?: string, country?: string, proxyType?: string): Promise<{
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+        pool: string;
+        country: string;
+    }>;
+    checkBalance(): Promise<{
+        balanceCents: number;
+        balanceUsd: number;
+        dcGbRemaining: string;
+        resGbRemaining: string;
+    }>;
+    checkUsage(days?: number): Promise<{
+        totalBytes: number;
+        totalCostUsd: number;
+        requestCount: number;
+        period: string;
+    }>;
+    getProxyConfig(): Promise<Record<string, unknown>>;
+    listSessions(): Promise<Record<string, unknown>>;
+    createAgenticWallet(label: string, spendingLimitCents: number, dailyLimitCents?: number, allowedDomains?: string[]): Promise<Record<string, unknown>>;
+    updateWalletPolicy(walletId: string, dailyLimitCents?: number | null, allowedDomains?: string[] | null): Promise<Record<string, unknown>>;
+    fundAgenticWallet(walletId: string, amountCents: number): Promise<Record<string, unknown>>;
+    agenticWalletBalance(walletId: string): Promise<Record<string, unknown>>;
+    listAgenticWallets(): Promise<Record<string, unknown>>;
+    agenticTransactions(walletId: string, limit?: number): Promise<Record<string, unknown>>;
+    freezeAgenticWallet(walletId: string): Promise<Record<string, unknown>>;
+    unfreezeAgenticWallet(walletId: string): Promise<Record<string, unknown>>;
+    deleteAgenticWallet(walletId: string): Promise<Record<string, unknown>>;
+    createTeam(name: string, maxMembers?: number): Promise<Record<string, unknown>>;
+    listTeams(): Promise<Record<string, unknown>>;
+    teamDetails(teamId: string): Promise<Record<string, unknown>>;
+    teamFund(teamId: string, amountCents: number): Promise<Record<string, unknown>>;
+    teamCreateKey(teamId: string, label: string): Promise<Record<string, unknown>>;
+    teamUsage(teamId: string, limit?: number): Promise<Record<string, unknown>>;
+    updateTeam(teamId: string, name?: string, maxMembers?: number): Promise<Record<string, unknown>>;
+    updateTeamMemberRole(teamId: string, userId: string, role: string): Promise<Record<string, unknown>>;
+    topupPaypal(amountCents: number): Promise<Record<string, unknown>>;
+    x402Info(): Promise<Record<string, unknown>>;
+    getTools(): (import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+        pool: string;
+        country: string;
+    } | {
+        status: number;
+        headers: {};
+        body: string;
+        pool: any;
+        country: any;
+        error: string;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_proxied_fetch", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<unknown, {
+        balanceCents: number;
+        balanceUsd: number;
+        dcGbRemaining: string;
+        resGbRemaining: string;
+    } | {
+        balanceCents: number;
+        balanceUsd: number;
+        dcGbRemaining: string;
+        resGbRemaining: string;
+        error: string;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_check_balance", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        totalBytes: number;
+        totalCostUsd: number;
+        requestCount: number;
+        period: string;
+    } | {
+        totalBytes: number;
+        totalCostUsd: number;
+        requestCount: number;
+        period: string;
+        error: string;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_check_usage", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<unknown, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_get_proxy_config", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<unknown, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_list_sessions", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_create_agentic_wallet", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_fund_agentic_wallet", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_agentic_wallet_balance", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<unknown, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_list_agentic_wallets", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_agentic_transactions", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_freeze_agentic_wallet", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_unfreeze_agentic_wallet", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_delete_agentic_wallet", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_update_wallet_policy", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_create_team", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<unknown, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_list_teams", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_team_details", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_team_fund", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_team_create_key", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_team_usage", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_update_team", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_update_team_member_role", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<{
+        context: any;
+    }, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_topup_paypal", unknown> | import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).Tool<unknown, {
+        error?: string | undefined;
+        data?: unknown;
+    }, unknown, unknown, import("@mastra/core/tools", { with: { "resolution-mode": "import" } }).ToolExecutionContext<unknown, unknown, unknown>, "dominusnode_x402_info", unknown>)[];
+}