nport 2.0.7 → 2.1.1

package/CHANGELOG.md

@@ -5,6 +5,137 @@ All notable changes to NPort will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.1] - 2026-01-27
+
+### Fixed
+- 🐛 **NPM Package Build**: Fixed missing `dist/` folder in published package
+  - Added build step to npm-publish workflow before publishing
+  - Package now includes compiled JavaScript files correctly
+
+### Added
+- 🚀 **CI/CD Workflows**: Added GitHub Actions for automated deployments
+  - `ci.yml`: Runs tests on push to main and pull requests
+  - `deploy-server.yml`: Auto-deploys Cloudflare Worker on server changes
+  - `deploy-website.yml`: Auto-deploys website to Cloudflare Pages on changes
+- 🧪 **Server Test Configuration**: Fixed Vitest config for CI environment
+  - Added miniflare bindings for test environment variables
+  - Tests now pass in CI without `.dev.vars` file
+- ⚙️ **Wrangler Configuration**: Added `preview_urls` setting to suppress warnings
+
+## [2.1.0] - 2026-01-27
+
+### Added
+- 🔷 **Full TypeScript Migration**: Complete rewrite of CLI and Server in TypeScript
+  - Strict type checking enabled across the entire codebase
+  - All modules converted from JavaScript to TypeScript
+  - Type-safe interfaces for configuration, tunnels, analytics, and i18n
+  - Better IDE support with IntelliSense and autocompletion
+- 📚 **Comprehensive Documentation**: New docs folder with detailed guides
+  - `docs/ARCHITECTURE.md`: System overview, component diagrams, and data flow
+  - `docs/API.md`: Complete API reference with endpoints and examples
+  - `docs/CONTRIBUTING.md`: Contribution guidelines and development setup
+- 🤖 **AI Context Support**: Added `.ai/context.md` for AI-assisted development
+  - Project structure and key patterns documented
+  - Coding conventions and architecture decisions
+  - Makes AI pair programming more effective
+- 🧪 **Unit Testing with Vitest**: Comprehensive test suite for CLI
+  - Tests for argument parsing (`tests/args.test.ts`)
+  - Tests for version comparison (`tests/version.test.ts`)
+  - Tests for state management (`tests/state.test.ts`)
+  - Easy to run with `npm test`
+- 📋 **Code Ownership**: Added `.github/CODEOWNERS` file
+  - Clear ownership for code review assignments
+  - Faster PR reviews with automatic reviewer assignment
+- 📝 **Cursor Rules**: Added `.cursorrules` for consistent AI assistance
+  - Project-specific coding conventions
+  - TypeScript and naming guidelines
+  - Common patterns and anti-patterns
+- 🔄 **Auto-download Cloudflared**: Binary downloads automatically on first run
+  - No need to run separate install commands
+  - Seamless first-time user experience
+  - Progress indicator during download
+- 🔒 **Protected Subdomain Support**: Enhanced error handling for reserved subdomains
+  - User-friendly error message when trying to create protected subdomains (like `api`)
+  - Formatted error output matching existing error style
+  - Helpful suggestions to use alternative subdomain names
+  - Prevents accidental use of backend service subdomains
+- 📋 **TODO Management**: Added `TODO.md` for tracking planned features
+  - Move time limit enforcement to backend
+  - Update README powered-by section
+  - Track terminal link clicks
+
+### Changed
+- 🏗️ **Project Structure**: Reorganized for better maintainability
+  - All source code in `src/` directory
+  - Type definitions in `src/types/`
+  - Shared constants in `src/constants.ts`
+  - Tests in `tests/` directory
+- 📦 **Build System**: Updated to TypeScript compilation
+  - Uses `tsc` for compilation
+  - Output to `dist/` directory
+  - Source maps for debugging
+- 🔧 **Development Workflow**: Improved developer experience
+  - `npm run dev` for watch mode
+  - `npm run build` for production
+  - `npm test` for running tests
+  - `npm run lint` for type checking
+- ⚙️ **System Requirements**: Updated to Node.js 20+
+  - Minimum Node.js version: 20.0.0
+  - Minimum npm version: 10.0.0
+  - Better security and performance with latest LTS
+
+### Improved
+- ✨ **Better Error Messages**: Enhanced user feedback for protected subdomains
+  - Catches `SUBDOMAIN_PROTECTED` errors from backend
+  - Formats error messages consistently with other error types
+  - Shows actionable options when subdomain is reserved
+
+### Fixed
+- 🐛 **Intel Mac Binary Download**: Fixed cloudflared binary download on Intel Macs
+  - Node.js reports architecture as `x64`, not `amd64` - now correctly mapped
+  - Fixed ARM64 Macs to download the correct `cloudflared-darwin-arm64.tgz` binary
+  - Previously ARM64 Macs were incorrectly downloading the AMD64 binary
+
+### Server (v1.1.0)
+- 🔷 **TypeScript Migration**: Server fully converted to TypeScript
+  - Type-safe Cloudflare Worker handlers
+  - Properly typed API responses
+  - Full type coverage for Cloudflare API interactions
+- 🧪 **Server Tests**: Updated test suite for TypeScript
+  - Vitest with Cloudflare Workers pool
+  - Tests for all API endpoints
+  - Scheduled task testing
+- 🔒 **Protected Subdomains**: Infrastructure to protect critical subdomains from deletion or overwriting
+  - New `PROTECTED_SUBDOMAINS` constant array for easy management of reserved subdomains
+  - Default protected subdomain: `api` (reserved for NPort backend service)
+  - Easy to add more protected subdomains by updating the array
+  - Protected subdomains are blocked at both creation and cleanup stages
+- 🛡️ **Backend Service Protection**: Prevents accidental deletion or overwriting of production services
+  - `api` subdomain is now protected from user creation attempts
+  - Scheduled cleanup job skips protected subdomains
+  - Returns clear error message when users try to use protected names
+- 🔧 **Manual Cleanup Endpoint**: Added `GET /scheduled` endpoint to manually trigger cleanup
+  - Useful for testing and on-demand cleanup
+  - Respects protected subdomains configuration
+  - Returns JSON response with cleanup results
+
+### Technical Details
+- **Type System**: 
+  - `TunnelConfig`, `TunnelState`, `ConnectionInfo` interfaces
+  - `AnalyticsParams`, `VersionInfo`, `I18nStrings` types
+  - `LogPatterns` with readonly arrays for constants
+- **ESM Compliance**: All imports use `.js` extensions as required
+- **Constants**: Centralized in `src/constants.ts` with `as const` assertions
+- **Error Handling**: Type-safe error boundaries throughout
+
+### Migration
+- Automatic migration - no manual steps required
+- Existing configuration in `~/.nport/config.json` remains compatible
+- All CLI flags and options unchanged
+
+### Breaking Changes
+- None - fully backward compatible!
+
 ## [2.0.7] - 2026-01-14
 
 ### Added
@@ -186,6 +317,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Version Upgrade Guide
 
+### From 2.0.7 to 2.1.0
+
+```bash
+npm install -g nport@latest
+```
+
+**What's New:**
+
+1. **Full TypeScript Rewrite**
+   - Both CLI and Server now fully typed
+   - Better IDE support and autocompletion
+   - Catches errors at compile time
+
+2. **Comprehensive Documentation**
+   - Architecture guide in `docs/ARCHITECTURE.md`
+   - API reference in `docs/API.md`
+   - Contributing guide in `docs/CONTRIBUTING.md`
+
+3. **Unit Testing**
+   - Run tests with `npm test`
+   - Covers argument parsing, version checks, state management
+
+4. **Auto-download Cloudflared**
+   - Binary downloads automatically on first `nport` run
+   - No separate install step needed
+
+5. **AI-Friendly Codebase**
+   - `.ai/context.md` for AI assistants
+   - `.cursorrules` for consistent AI suggestions
+   - JSDoc comments throughout
+
+**For Contributors:**
+```bash
+git clone https://github.com/tuanngocptn/nport
+cd nport
+npm install
+npm run build
+npm run dev  # Watch mode
+```
+
+**Breaking Changes:** None - fully backward compatible!
+
 ### From 2.0.6 to 2.0.7
 
 ```bash

package/README.md

@@ -6,6 +6,7 @@
 [![NPM](https://img.shields.io/npm/v/nport?color=red&logo=npm)](https://www.npmjs.com/package/nport)
 [![Website](https://img.shields.io/website?url=https%3A%2F%2Fnport.link&up_message=nport.link&up_color=blue&down_color=lightgrey&down_message=offline)](https://nport.link)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
 
 ## What is NPort?
 
@@ -269,25 +270,30 @@ Internet → Cloudflare Edge → Cloudflare Tunnel → Your localhost:3000
 
 ## 🏗️ Project Structure
 
-NPort uses a modular architecture for better maintainability:
-
 ```
 nport/
-├── index.js              # Main entry point
-├── src/
-│   ├── analytics.js      # Analytics tracking
-│   ├── api.js            # Backend API client
-│   ├── args.js           # CLI argument parser
-│   ├── binary.js         # Cloudflared binary manager
-│   ├── bin-manager.js    # Binary download/installation
-│   ├── config.js         # Configuration constants
-│   ├── lang.js           # Multilingual support
-│   ├── state.js          # Application state
-│   ├── tunnel.js         # Tunnel orchestration
-│   ├── ui.js             # User interface display
-│   └── version.js        # Version management
-└── bin/
-    └── cloudflared       # Cloudflare tunnel binary
+├── src/                         # TypeScript source files
+│   ├── index.ts                 # Entry point
+│   ├── tunnel.ts                # Tunnel orchestration
+│   ├── api.ts                   # Backend API client
+│   ├── args.ts                  # CLI argument parser
+│   ├── binary.ts                # Cloudflared process manager
+│   ├── ui.ts                    # Console UI components
+│   ├── lang.ts                  # Multilingual support
+│   ├── types/                   # TypeScript type definitions
+│   └── ...
+│
+├── tests/                       # Unit tests (vitest)
+├── dist/                        # Compiled output
+├── bin/                         # cloudflared binary (downloaded)
+│
+├── server/                      # Backend (Cloudflare Worker)
+├── website/                     # Static landing page
+├── docs/                        # Documentation
+│   ├── ARCHITECTURE.md          # Technical architecture
+│   ├── API.md                   # API reference
+│   └── CONTRIBUTING.md          # Contribution guide
+└── .ai/                         # AI context files
 ```
 
 ## 🛡️ Security
@@ -370,7 +376,7 @@ Then select your preferred language from the menu.
 - 🇺🇸 **English** (`en`) - Default
 - 🇻🇳 **Vietnamese** (`vi`) - Tiếng Việt
 
-Want to add your language? Contributions are welcome! Check out `src/lang.js` to see how easy it is to add translations.
+Want to add your language? Contributions are welcome! Check out the [Contributing Guide](docs/CONTRIBUTING.md).
 
 ## 🤝 Contributing
 
@@ -382,22 +388,26 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
-### Adding a New Language
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for detailed guidelines.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/tuanngocptn/nport.git
+cd nport
+
+# Install dependencies
+npm install
 
-To add a new language:
+# Build TypeScript
+npm run build
 
-1. Open `src/lang.js`
-2. Add your language code to `availableLanguages` array
-3. Add translations to the `TRANSLATIONS` object
-4. Submit a PR!
+# Run tests
+npm test
 
-Example:
-```javascript
-const TRANSLATIONS = {
-  en: { /* English translations */ },
-  vi: { /* Vietnamese translations */ },
-  es: { /* Your Spanish translations */ },
-};
+# Run CLI locally
+node dist/index.js 3000 -s test
 ```
 
 ## 💖 Support
@@ -408,7 +418,7 @@ If you find NPort useful, please consider supporting the project:
 - ☕ [Buy me a coffee](https://buymeacoffee.com/tuanngocptn)
 - 💬 Share with your friends and colleagues
 - 🐛 [Report bugs](https://github.com/tuanngocptn/nport/issues)
-- 🌍 [Add translations](https://github.com/tuanngocptn/nport/blob/main/src/lang.js)
+- 🌍 [Add translations](docs/CONTRIBUTING.md#adding-translations)
 
 ## 📄 License
 

package/dist/analytics.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Analytics Manager
+ */
+declare class AnalyticsManager {
+    private userId;
+    private sessionId;
+    private disabled;
+    constructor();
+    /**
+     * Initializes analytics.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Gets or creates a persistent user ID.
+     */
+    private getUserId;
+    /**
+     * Generates an anonymous user ID.
+     */
+    private generateAnonymousId;
+    /**
+     * Generates a session ID.
+     */
+    private generateSessionId;
+    /**
+     * Tracks an event.
+     */
+    private trackEvent;
+    /**
+     * Builds GA4 payload.
+     */
+    private buildPayload;
+    /**
+     * Gets system information.
+     */
+    private getSystemInfo;
+    /**
+     * Tracks CLI start.
+     */
+    trackCliStart(port: number, subdomain: string, version: string): void;
+    /**
+     * Tracks tunnel creation.
+     */
+    trackTunnelCreated(subdomain: string, port: number): void;
+    /**
+     * Tracks tunnel error.
+     */
+    trackTunnelError(errorType: string, errorMessage: string): void;
+    /**
+     * Tracks tunnel shutdown.
+     */
+    trackTunnelShutdown(reason: string, durationSeconds: number): void;
+    /**
+     * Tracks update available.
+     */
+    trackUpdateAvailable(currentVersion: string, latestVersion: string): void;
+}
+export declare const analytics: AnalyticsManager;
+export {};

package/dist/analytics.js

@@ -0,0 +1,193 @@
+import axios from 'axios';
+import { createHash, randomUUID } from 'crypto';
+import os from 'os';
+import fs from 'fs';
+import path from 'path';
+import { ANALYTICS_TIMEOUT } from './constants.js';
+/**
+ * Firebase/GA4 Configuration
+ */
+const FIREBASE_CONFIG = {
+    measurementId: 'G-8MYXZL6PGD',
+    apiSecret: process.env.NPORT_ANALYTICS_SECRET || 'YOUR_API_SECRET_HERE',
+};
+const ANALYTICS_CONFIG = {
+    enabled: true,
+    debug: process.env.NPORT_DEBUG === 'true',
+    timeout: ANALYTICS_TIMEOUT,
+    userIdFile: path.join(os.homedir(), '.nport', 'analytics-id'),
+};
+/**
+ * Analytics Manager
+ */
+class AnalyticsManager {
+    userId = null;
+    sessionId = null;
+    disabled = false;
+    constructor() {
+        if (process.env.NPORT_ANALYTICS === 'false') {
+            this.disabled = true;
+        }
+    }
+    /**
+     * Initializes analytics.
+     */
+    async initialize() {
+        if (this.disabled)
+            return;
+        if (!FIREBASE_CONFIG.apiSecret || FIREBASE_CONFIG.apiSecret === 'YOUR_API_SECRET_HERE') {
+            if (ANALYTICS_CONFIG.debug) {
+                console.warn('[Analytics] API secret not configured. Analytics disabled.');
+            }
+            this.disabled = true;
+            return;
+        }
+        try {
+            this.userId = await this.getUserId();
+            this.sessionId = this.generateSessionId();
+            if (ANALYTICS_CONFIG.debug) {
+                console.log('[Analytics] Initialized successfully');
+            }
+        }
+        catch {
+            this.disabled = true;
+        }
+    }
+    /**
+     * Gets or creates a persistent user ID.
+     */
+    async getUserId() {
+        try {
+            const configDir = path.join(os.homedir(), '.nport');
+            if (!fs.existsSync(configDir)) {
+                fs.mkdirSync(configDir, { recursive: true });
+            }
+            if (fs.existsSync(ANALYTICS_CONFIG.userIdFile)) {
+                const userId = fs.readFileSync(ANALYTICS_CONFIG.userIdFile, 'utf8').trim();
+                if (userId)
+                    return userId;
+            }
+            const userId = this.generateAnonymousId();
+            fs.writeFileSync(ANALYTICS_CONFIG.userIdFile, userId, 'utf8');
+            return userId;
+        }
+        catch {
+            return this.generateAnonymousId();
+        }
+    }
+    /**
+     * Generates an anonymous user ID.
+     */
+    generateAnonymousId() {
+        const machineId = [
+            os.hostname(),
+            os.platform(),
+            os.arch(),
+            os.homedir(),
+        ].join('-');
+        return createHash('sha256').update(machineId).digest('hex').substring(0, 32);
+    }
+    /**
+     * Generates a session ID.
+     */
+    generateSessionId() {
+        return randomUUID();
+    }
+    /**
+     * Tracks an event.
+     */
+    async trackEvent(eventName, params = {}) {
+        if (this.disabled || !ANALYTICS_CONFIG.enabled || !this.userId)
+            return;
+        try {
+            const payload = this.buildPayload(eventName, params);
+            axios.post(`https://www.google-analytics.com/mp/collect?measurement_id=${FIREBASE_CONFIG.measurementId}&api_secret=${FIREBASE_CONFIG.apiSecret}`, payload, {
+                timeout: ANALYTICS_CONFIG.timeout,
+                headers: { 'Content-Type': 'application/json' },
+            }).catch(() => {
+                // Silently fail
+            });
+        }
+        catch {
+            // Silently fail
+        }
+    }
+    /**
+     * Builds GA4 payload.
+     */
+    buildPayload(eventName, params) {
+        return {
+            client_id: this.userId,
+            events: [
+                {
+                    name: eventName,
+                    params: {
+                        session_id: this.sessionId,
+                        engagement_time_msec: '100',
+                        ...this.getSystemInfo(),
+                        ...params,
+                    },
+                },
+            ],
+        };
+    }
+    /**
+     * Gets system information.
+     */
+    getSystemInfo() {
+        return {
+            os_platform: os.platform(),
+            os_version: os.release(),
+            os_arch: os.arch(),
+            node_version: process.version,
+        };
+    }
+    /**
+     * Tracks CLI start.
+     */
+    trackCliStart(port, subdomain, version) {
+        this.trackEvent('cli_start', {
+            port: String(port),
+            has_custom_subdomain: subdomain && !subdomain.startsWith('user-'),
+            cli_version: version,
+        });
+    }
+    /**
+     * Tracks tunnel creation.
+     */
+    trackTunnelCreated(subdomain, port) {
+        this.trackEvent('tunnel_created', {
+            subdomain_type: subdomain.startsWith('user-') ? 'random' : 'custom',
+            port: String(port),
+        });
+    }
+    /**
+     * Tracks tunnel error.
+     */
+    trackTunnelError(errorType, errorMessage) {
+        this.trackEvent('tunnel_error', {
+            error_type: errorType,
+            error_message: errorMessage.substring(0, 100),
+        });
+    }
+    /**
+     * Tracks tunnel shutdown.
+     */
+    trackTunnelShutdown(reason, durationSeconds) {
+        this.trackEvent('tunnel_shutdown', {
+            shutdown_reason: reason,
+            duration_seconds: String(Math.floor(durationSeconds)),
+        });
+    }
+    /**
+     * Tracks update available.
+     */
+    trackUpdateAvailable(currentVersion, latestVersion) {
+        this.trackEvent('update_available', {
+            current_version: currentVersion,
+            latest_version: latestVersion,
+        });
+    }
+}
+export const analytics = new AnalyticsManager();
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"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"}

package/dist/api.d.ts

@@ -0,0 +1,20 @@
+import type { TunnelResponse } from './types/index.js';
+/**
+ * API Client
+ *
+ * Handles all communication with the NPort backend service.
+ */
+export declare class APIClient {
+    /**
+     * Creates a new Cloudflare tunnel via the backend API.
+     */
+    static createTunnel(subdomain: string, backendUrl?: string | null): Promise<TunnelResponse>;
+    /**
+     * Deletes an existing tunnel.
+     */
+    static deleteTunnel(subdomain: string, tunnelId: string, backendUrl?: string | null): Promise<void>;
+    /**
+     * Transforms API errors into user-friendly messages.
+     */
+    private static handleError;
+}

package/dist/api.js

@@ -0,0 +1,85 @@
+import axios from 'axios';
+import chalk from 'chalk';
+import { CONFIG } from './config.js';
+import { state } from './state.js';
+/**
+ * API Client
+ *
+ * Handles all communication with the NPort backend service.
+ */
+export class APIClient {
+    /**
+     * Creates a new Cloudflare tunnel via the backend API.
+     */
+    static async createTunnel(subdomain, backendUrl = null) {
+        const url = backendUrl || CONFIG.BACKEND_URL;
+        try {
+            const { data } = await axios.post(url, { subdomain });
+            if (!data.success) {
+                throw new Error(data.error || 'Unknown error from backend');
+            }
+            return {
+                tunnelId: data.tunnelId,
+                tunnelToken: data.tunnelToken,
+                url: data.url,
+            };
+        }
+        catch (error) {
+            throw this.handleError(error, subdomain);
+        }
+    }
+    /**
+     * Deletes an existing tunnel.
+     */
+    static async deleteTunnel(subdomain, tunnelId, backendUrl = null) {
+        const url = backendUrl || CONFIG.BACKEND_URL;
+        await axios.delete(url, {
+            data: { subdomain, tunnelId },
+        });
+    }
+    /**
+     * Transforms API errors into user-friendly messages.
+     */
+    static handleError(error, subdomain) {
+        const errorMsg = error.response?.data?.error;
+        if (errorMsg) {
+            if (errorMsg.includes('SUBDOMAIN_PROTECTED:')) {
+                return new Error(`Subdomain "${subdomain}" is already taken or in use.\n\n` +
+                    chalk.yellow('💡 Try one of these options:\n') +
+                    chalk.gray('   1. Choose a different subdomain: ') +
+                    chalk.cyan(`nport ${state.port || CONFIG.DEFAULT_PORT} -s ${subdomain}-v2\n`) +
+                    chalk.gray('   2. Use a random subdomain:       ') +
+                    chalk.cyan(`nport ${state.port || CONFIG.DEFAULT_PORT}\n`) +
+                    chalk.gray('   3. Wait a few minutes and retry if you just stopped a tunnel with this name'));
+            }
+            if (errorMsg.includes('SUBDOMAIN_IN_USE:') ||
+                errorMsg.includes('currently in use') ||
+                errorMsg.includes('already exists and is currently active')) {
+                return new Error(chalk.red(`✗ Subdomain "${subdomain}" is already in use!\n\n`) +
+                    chalk.yellow('💡 This subdomain is currently being used by another active tunnel.\n\n') +
+                    chalk.white('Choose a different subdomain:\n') +
+                    chalk.gray('   1. Add a suffix:     ') +
+                    chalk.cyan(`nport ${state.port || CONFIG.DEFAULT_PORT} -s ${subdomain}-2\n`) +
+                    chalk.gray('   2. Try a variation:  ') +
+                    chalk.cyan(`nport ${state.port || CONFIG.DEFAULT_PORT} -s my-${subdomain}\n`) +
+                    chalk.gray('   3. Use random name:  ') +
+                    chalk.cyan(`nport ${state.port || CONFIG.DEFAULT_PORT}\n`));
+            }
+            if (errorMsg.includes('already have a tunnel') || errorMsg.includes('[1013]')) {
+                return new Error(`Subdomain "${subdomain}" is already taken or in use.\n\n` +
+                    chalk.yellow('💡 Try one of these options:\n') +
+                    chalk.gray('   1. Choose a different subdomain: ') +
+                    chalk.cyan(`nport ${state.port || CONFIG.DEFAULT_PORT} -s ${subdomain}-v2\n`) +
+                    chalk.gray('   2. Use a random subdomain:       ') +
+                    chalk.cyan(`nport ${state.port || CONFIG.DEFAULT_PORT}\n`) +
+                    chalk.gray('   3. Wait a few minutes and retry if you just stopped a tunnel with this name'));
+            }
+            return new Error(`Backend Error: ${errorMsg}`);
+        }
+        if (error.response) {
+            return new Error(`Backend Error: ${JSON.stringify(error.response.data, null, 2)}`);
+        }
+        return error;
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}