npm package: @hyperwire/client
Description: A secure development tunnel client that allows you to expose your local development server to the internet through a secure WebSocket connection.
Latest version: 1.0.2

# Wire Client

A secure development tunnel client that allows you to expose your local development server to the internet through a secure WebSocket connection.

## Features

- 🔐 **Secure Authentication** - Uses PocketBase for user authentication
- 🌐 **Public URLs** - Get public HTTPS URLs for your local development servers
- ⚡ **Real-time** - WebSocket-based tunneling for low latency
- 🎯 **Custom Subdomains** - Optional custom subdomain support
- 📦 **Easy CLI** - Simple command-line interface

## Installation

### From Source

```bash
# Clone the repository
git clone <repository-url>
cd wire/client

# Install dependencies
npm install

# Build the project
npm run build

# Install globally (optional)
npm link
```

### Development

```bash
# Run in development mode
npm run dev

# Build for production
npm run build
```

## Usage

### 1. Login

First, authenticate with your PocketBase instance:

```bash
wire login
```

You'll be prompted for:

- PocketBase URL (e.g., `https://your-pocketbase-instance.com`)
- Email address
- Password

### 2. Start Your Application

**Important**: Start your local application with the `--host` flag to ensure it accepts connections from all interfaces:

```bash
# For most development servers
npm start -- --host
# or
yarn start --host
```

### 3. Create a Tunnel

Create a tunnel to expose your local server:

```bash
# Basic usage - expose port 3000
wire tunnel 3000

# With custom subdomain
wire tunnel 3000 --sub myapp

# With custom server URL
wire tunnel 3000 --server https://your-wire-server.com
```

### 4. Access Your App

Once the tunnel is established, you'll get a public URL like:

- `https://random-subdomain.wishapp.io` (auto-generated)
- `https://myapp.wishapp.io` (with custom subdomain)

## Configuration

Configuration is stored in `~/.wire/config.json` and includes:

```json
{
  "pocketbaseUrl": "https://your-pocketbase-instance.com",
  "serverUrl": "http://wire.wishapp.io",
  "token": "your-auth-token",
  "email": "your-email@example.com"
}
```

## Commands

### `wire login`

Authenticate with PocketBase and save credentials locally.

### `wire tunnel <port>`

Create a tunnel to the specified local port.

**Options:**

- `--sub <subdomain>` - Use a custom subdomain
- `--server <url>` - Specify a custom Wire server URL (default: `http://wire.wishapp.io`)

## How It Works

1. **Authentication**: The client authenticates with PocketBase to get a secure token
2. **WebSocket Connection**: Establishes a WebSocket connection to the Wire server
3. **Request Forwarding**: Incoming HTTP requests are forwarded through the WebSocket to your local server
4. **Response Relay**: Responses from your local server are sent back through the WebSocket

## Architecture

```
Local App (port 3000) ←→ Wire Client ←→ WebSocket ←→ Wire Server ←→ Internet
```

The client acts as a bridge between your local development server and the public internet, forwarding requests and responses in real-time.

## Development

### Project Structure

```
client/
├── src/
│   ├── index.ts      # Core tunnel functionality
│   ├── cli.ts        # Command-line interface
│   ├── auth.ts       # Authentication logic
│   └── config.ts     # Configuration management
├── bin/
│   └── wire.ts       # CLI entry point
└── dist/             # Compiled JavaScript
```

### Building

```bash
# Development build with watch mode
npm run dev

# Production build
npm run build

# Run built version
npm start
```

## Dependencies

- **commander** - CLI framework
- **ws** - WebSocket client
- **node-fetch** - HTTP requests
- **chalk** - Terminal colors
- **readline-sync** - Interactive prompts